@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/generators/portable-knowledge.d.ts

@@ -2,6 +2,12 @@
  * Portable knowledge — reads canonical skills/rules from .productbrain/
  * and generates tool-specific copies for Cursor, Claude Code, etc.
  */
+import type { SurfaceProfile } from './surface-profiles.js';
+export interface WhenConditions {
+    when_stack?: string;
+    when_minStage?: string;
+    when_minGovernance?: string;
+}
 export interface CanonicalSkill {
     name: string;
     description: string;
@@ -10,6 +16,9 @@ export interface CanonicalSkill {
     sourcePath: string;
     targets?: string[];
     level?: string;
+    conditions?: WhenConditions;
+    /** 'team' = default (projected to committed adapter files); 'local' = local surface files only, never committed. */
+    persist?: 'local' | 'team';
 }
 export interface CanonicalRule {
     name: string;
@@ -20,22 +29,69 @@ export interface CanonicalRule {
     sourcePath: string;
     targets?: string[];
     level?: string;
+    conditions?: WhenConditions;
+    /** 'team' = default (projected to committed adapter files); 'local' = local surface files only, never committed. */
+    persist?: 'local' | 'team';
 }
-export type TargetName = 'cursor' | 'claude' | 'copilot';
+export type TargetName = 'cursor' | 'claude' | 'copilot' | 'codex';
+/**
+ * Returns true if the rule has persist: 'local'.
+ * Local rules are written to local surface files (.claude/rules/, .cursor/rules/)
+ * but must never be projected to committed adapter files (CLAUDE.md, AGENTS.md, etc.).
+ */
+export declare function isPersistLocal(rule: CanonicalRule): boolean;
 /** Returns true if the entry should be emitted to the given target. */
 export declare function shouldEmitToTarget(entry: CanonicalRule | CanonicalSkill, target: TargetName): boolean;
 export type HandshakeLevel = 'beginner' | 'intermediate' | 'expert';
 /**
- * Filter items by graduated level.
- * - If requestedLevel is undefined/null: return ALL items (backward compat).
+ * Maps workspace stage to the maximum allowed HandshakeLevel.
+ * Stages not listed here apply no cap (fail-open for unknown stages).
+ * Note: 'beginner' level allows only 'core' items; 'intermediate' allows core + intermediate.
+ */
+export declare const STAGE_TO_MAX_LEVEL: Record<string, HandshakeLevel>;
+/** Level ordering used to pick the more restrictive of two levels. */
+export declare const LEVEL_ORDER: HandshakeLevel[];
+/**
+ * Filter items by graduated level, with optional workspace stage-gating.
+ * - If requestedLevel is undefined/null AND stage provides no cap: return ALL items (backward compat).
  * - Items with no `level` field: always included (backward compat).
- * - Otherwise: include items whose level is within the hierarchy for requestedLevel.
+ * - Stage caps the effective level: blank→beginner, seed→intermediate, grounded/connected/critical→expert.
+ * - If stage is unknown or null: no cap applied (fail-open).
+ * - The effective level is min(requestedLevel, stageCap) — most restrictive wins.
  */
 export declare function filterByLevel<T extends {
     level?: string;
-}>(items: T[], requestedLevel?: string): T[];
+}>(items: T[], requestedLevel?: string, stage?: string): T[];
+/**
+ * Evaluate when_* conditions against the workspace profile and repo context.
+ * Returns { included, reasons }.
+ *
+ * Fail-open: if profile is null and profile-dependent conditions are present,
+ * the item is included (preserves current behavior when Chain is unavailable).
+ */
+export declare function evaluateConditions(conditions: WhenConditions, profile: {
+    stage: string;
+    totalRelations: number;
+} | null, repoContext: {
+    detectedStack: string[];
+}): {
+    included: boolean;
+    reasons: string[];
+};
 export declare function readCanonicalSkills(productbrainDir: string): CanonicalSkill[];
 export declare function readCanonicalRules(productbrainDir: string): CanonicalRule[];
+/**
+ * Read machine-local personal rules from .productbrain/.local/rules/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned rule has persist: 'local' set, preventing projection to committed adapter files.
+ */
+export declare function readPersonalLayer(productbrainDir: string): CanonicalRule[];
+/**
+ * Read machine-local personal skills from .productbrain/.local/skills/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned skill has persist: 'local' set, preventing projection to committed adapter files.
+ */
+export declare function readPersonalSkillsLayer(productbrainDir: string): CanonicalSkill[];
 /**
  * Strip transport-conditional sections from a skill body.
  *
@@ -53,20 +109,57 @@ export declare function stripTransportSections(body: string, target: TargetName)
  * Generate a Cursor SKILL.md from a canonical skill.
  * Cursor expects: name, description (with triggers embedded).
  */
-export declare function generateCursorSkill(skill: CanonicalSkill): string;
+export declare function generateCursorSkill(skill: CanonicalSkill, profile?: SurfaceProfile): string;
 /**
  * Generate a Cursor .mdc rule from a canonical rule.
  * Cursor expects: description, globs, alwaysApply.
  */
-export declare function generateCursorRule(rule: CanonicalRule): string;
+export declare function generateCursorRule(rule: CanonicalRule, profile?: SurfaceProfile): string;
+/**
+ * Apply batch-mode transformations to a skill body (DEC-283).
+ *
+ * Skills describe WHAT (intent). This generator produces HOW (batch-appropriate
+ * instructions). We transform interactive patterns without gutting the skill's
+ * logical structure and purpose.
+ *
+ * Transformations applied:
+ * 1. Strip sub-agent spawn patterns → inline steps
+ * 2. Strip user confirmation gates → autonomous proceed
+ * 3. Strip streaming/interactive references
+ * 4. Add batch governance header after first `#` heading
+ */
+export declare function applyBatchTransformations(body: string): string;
+/**
+ * Generate a Codex skill projection from a canonical skill.
+ * This is a repo-local markdown projection, not a separate authoring source.
+ *
+ * When profile.executionModel === 'batch', batch transformations are applied
+ * AFTER transport stripping and path replacement (DEC-283).
+ */
+export declare function generateCodexSkill(skill: CanonicalSkill, profile?: SurfaceProfile): string;
+/**
+ * Generate a Codex skill index/router file.
+ * AGENTS.md can point here so Codex has one obvious place to find available workflows.
+ */
+export declare function generateCodexSkillIndex(skills: CanonicalSkill[]): string;
+export interface CodexValidationWarning {
+    skillName: string;
+    pattern: string;
+    line: string;
+}
+/**
+ * Validate Codex-projected skills for references to capabilities Codex cannot execute.
+ * Scans the transport-stripped body (so claude-only blocks don't false-positive).
+ */
+export declare function validateCodexSkills(skills: CanonicalSkill[]): CodexValidationWarning[];
 /**
  * Generate a Claude Code .md rule from a canonical rule.
  * Claude Code expects: description, optional paths (array).
  */
-export declare function generateClaudeRule(rule: CanonicalRule): string;
+export declare function generateClaudeRule(rule: CanonicalRule, profile?: SurfaceProfile): string;
 /**
  * Generate a Claude Code skill-router.md — imperative skill activation rule.
  * Loaded automatically by Claude Code via .claude/rules/ with no paths (always active).
  */
-export declare function generateClaudeSkillRouter(skills: CanonicalSkill[]): string;
+export declare function generateClaudeSkillRouter(skills: CanonicalSkill[], profile?: SurfaceProfile): string;
 //# sourceMappingURL=portable-knowledge.d.ts.map

package/dist/generators/portable-knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"portable-knowledge.d.ts","sourceRoot":"","sources":["../../src/generators/portable-knowledge.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEzD,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAGrG;AAID,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,cAAc,GAAG,QAAQ,CAAC;AAUpE;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,CASpG;AAkED,wBAAgB,mBAAmB,CAAC,eAAe,EAAE,MAAM,GAAG,cAAc,EAAE,CAsB7E;AAED,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,GAAG,aAAa,EAAE,CAuB3E;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAa/E;AAID;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAyBjE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAc9D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAqB9D;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,CA4B1E"}
+{"version":3,"file":"portable-knowledge.d.ts","sourceRoot":"","sources":["../../src/generators/portable-knowledge.ts"],"names":[],"mappings":"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"}

package/dist/generators/portable-knowledge.js

@@ -5,8 +5,25 @@
 import { readdirSync, readFileSync, existsSync } from 'fs';
 import { join, basename } from 'path';
 import { MARKER } from './adapters.js';
+/**
+ * Committed adapter targets — these correspond to files that are checked into the repo.
+ * Rules with persist: 'local' must never be included in arrays that feed these targets.
+ */
+const COMMITTED_ADAPTER_TARGETS = new Set(['copilot', 'codex']);
+/**
+ * Returns true if the rule has persist: 'local'.
+ * Local rules are written to local surface files (.claude/rules/, .cursor/rules/)
+ * but must never be projected to committed adapter files (CLAUDE.md, AGENTS.md, etc.).
+ */
+export function isPersistLocal(rule) {
+    return rule.persist === 'local';
+}
 /** Returns true if the entry should be emitted to the given target. */
 export function shouldEmitToTarget(entry, target) {
+    // Local rules must not go to committed adapter targets (copilot, codex)
+    if ('persist' in entry && entry.persist === 'local' && COMMITTED_ADAPTER_TARGETS.has(target)) {
+        return false;
+    }
     if (!entry.targets)
         return true;
     return entry.targets.includes(target);
@@ -18,20 +35,120 @@ const LEVEL_HIERARCHY = {
 };
 const VALID_LEVELS = new Set(Object.keys(LEVEL_HIERARCHY));
 /**
- * Filter items by graduated level.
- * - If requestedLevel is undefined/null: return ALL items (backward compat).
+ * Maps workspace stage to the maximum allowed HandshakeLevel.
+ * Stages not listed here apply no cap (fail-open for unknown stages).
+ * Note: 'beginner' level allows only 'core' items; 'intermediate' allows core + intermediate.
+ */
+export const STAGE_TO_MAX_LEVEL = {
+    blank: 'beginner',
+    seed: 'intermediate',
+    grounded: 'expert',
+    connected: 'expert',
+    critical: 'expert',
+};
+/** Level ordering used to pick the more restrictive of two levels. */
+export const LEVEL_ORDER = ['beginner', 'intermediate', 'expert'];
+/**
+ * Pick the more restrictive of two levels.
+ * If either is undefined, returns the other (or undefined if both are).
+ */
+function capLevel(requested, cap) {
+    if (!requested && !cap)
+        return undefined;
+    if (!requested)
+        return cap;
+    if (!cap)
+        return requested;
+    const requestedIdx = LEVEL_ORDER.indexOf(requested);
+    const capIdx = LEVEL_ORDER.indexOf(cap);
+    return LEVEL_ORDER[Math.min(requestedIdx, capIdx)];
+}
+/**
+ * Filter items by graduated level, with optional workspace stage-gating.
+ * - If requestedLevel is undefined/null AND stage provides no cap: return ALL items (backward compat).
  * - Items with no `level` field: always included (backward compat).
- * - Otherwise: include items whose level is within the hierarchy for requestedLevel.
+ * - Stage caps the effective level: blank→beginner, seed→intermediate, grounded/connected/critical→expert.
+ * - If stage is unknown or null: no cap applied (fail-open).
+ * - The effective level is min(requestedLevel, stageCap) — most restrictive wins.
  */
-export function filterByLevel(items, requestedLevel) {
-    if (!requestedLevel)
-        return items;
-    if (!VALID_LEVELS.has(requestedLevel)) {
-        throw new Error(`Unknown level "${requestedLevel}". Valid levels: ${[...VALID_LEVELS].join(', ')}`);
+export function filterByLevel(items, requestedLevel, stage) {
+    // Resolve stage cap (fail-open for unknown/undefined stage)
+    const stageCap = stage ? STAGE_TO_MAX_LEVEL[stage] : undefined;
+    // Resolve requested level as typed enum (validate if provided)
+    let typedRequested;
+    if (requestedLevel) {
+        if (!VALID_LEVELS.has(requestedLevel)) {
+            throw new Error(`Unknown level "${requestedLevel}". Valid levels: ${[...VALID_LEVELS].join(', ')}`);
+        }
+        typedRequested = requestedLevel;
     }
-    const allowedLevels = LEVEL_HIERARCHY[requestedLevel];
+    // Determine effective level (most restrictive)
+    const effectiveLevel = capLevel(typedRequested, stageCap);
+    // No effective level — return all items (backward compat)
+    if (!effectiveLevel)
+        return items;
+    const allowedLevels = LEVEL_HIERARCHY[effectiveLevel];
     return items.filter((item) => !item.level || allowedLevels.includes(item.level));
 }
+// ── Stage ordering ────────────────────────────────────────────────────
+const STAGE_ORDER = ['blank', 'seed', 'grounded', 'connected', 'critical'];
+/**
+ * Evaluate when_* conditions against the workspace profile and repo context.
+ * Returns { included, reasons }.
+ *
+ * Fail-open: if profile is null and profile-dependent conditions are present,
+ * the item is included (preserves current behavior when Chain is unavailable).
+ */
+export function evaluateConditions(conditions, profile, repoContext) {
+    const hasProfileConditions = conditions.when_minStage !== undefined || conditions.when_minGovernance !== undefined;
+    const hasStackCondition = conditions.when_stack !== undefined;
+    // No when_* keys at all — always include
+    if (!hasProfileConditions && !hasStackCondition) {
+        return { included: true, reasons: ['no conditions'] };
+    }
+    // Fail-open: profile unavailable but profile-dependent conditions present
+    if (profile === null && hasProfileConditions) {
+        return { included: true, reasons: ['no workspace profile — fail-open'] };
+    }
+    const reasons = [];
+    let included = true;
+    // when_stack: evaluated against repoContext (not profile)
+    if (conditions.when_stack !== undefined) {
+        const needle = conditions.when_stack.toLowerCase();
+        const match = repoContext.detectedStack.some((s) => s.toLowerCase() === needle);
+        if (!match) {
+            included = false;
+            reasons.push(`when_stack=${conditions.when_stack} not in detected stack [${repoContext.detectedStack.join(', ')}]`);
+        }
+        else {
+            reasons.push(`when_stack=${conditions.when_stack} matched`);
+        }
+    }
+    // when_minStage: profile guaranteed non-null here when this condition is present
+    if (conditions.when_minStage !== undefined && profile !== null) {
+        const profileIdx = STAGE_ORDER.indexOf(profile.stage);
+        const thresholdIdx = STAGE_ORDER.indexOf(conditions.when_minStage);
+        if (thresholdIdx === -1 || profileIdx === -1 || profileIdx < thresholdIdx) {
+            included = false;
+            reasons.push(`when_minStage=${conditions.when_minStage} but workspace stage=${profile.stage}`);
+        }
+        else {
+            reasons.push(`when_minStage=${conditions.when_minStage} satisfied (stage=${profile.stage})`);
+        }
+    }
+    // when_minGovernance: profile guaranteed non-null here when this condition is present
+    if (conditions.when_minGovernance !== undefined && profile !== null) {
+        const threshold = parseInt(conditions.when_minGovernance, 10);
+        if (isNaN(threshold) || profile.totalRelations < threshold) {
+            included = false;
+            reasons.push(`when_minGovernance=${conditions.when_minGovernance} but totalRelations=${profile.totalRelations}`);
+        }
+        else {
+            reasons.push(`when_minGovernance=${conditions.when_minGovernance} satisfied (totalRelations=${profile.totalRelations})`);
+        }
+    }
+    return { included, reasons };
+}
 // ── Frontmatter parser ─────────────────────────────────────────────────
 function parseFrontmatter(raw) {
     const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
@@ -94,7 +211,18 @@ export function readCanonicalSkills(productbrainDir) {
         const triggers = arrayFields.get('triggers') ?? [];
         const targets = arrayFields.get('targets');
         const level = fields.get('level');
-        skills.push({ name, description, triggers, body, sourcePath: filePath, targets: targets?.length ? targets : undefined, level: level || undefined });
+        const conditions = {};
+        const whenStack = fields.get('when_stack');
+        const whenMinStage = fields.get('when_minStage');
+        const whenMinGovernance = fields.get('when_minGovernance');
+        if (whenStack)
+            conditions.when_stack = whenStack;
+        if (whenMinStage)
+            conditions.when_minStage = whenMinStage;
+        if (whenMinGovernance)
+            conditions.when_minGovernance = whenMinGovernance;
+        const hasConditions = Object.keys(conditions).length > 0;
+        skills.push({ name, description, triggers, body, sourcePath: filePath, targets: targets?.length ? targets : undefined, level: level || undefined, conditions: hasConditions ? conditions : undefined });
     }
     return skills.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -114,10 +242,113 @@ export function readCanonicalRules(productbrainDir) {
         const autoApply = fields.get('autoApply') === 'true';
         const targets = arrayFields.get('targets');
         const level = fields.get('level');
-        rules.push({ name, description, scope, autoApply, body, sourcePath: filePath, targets: targets?.length ? targets : undefined, level: level || undefined });
+        const conditions = {};
+        const whenStack = fields.get('when_stack');
+        const whenMinStage = fields.get('when_minStage');
+        const whenMinGovernance = fields.get('when_minGovernance');
+        if (whenStack)
+            conditions.when_stack = whenStack;
+        if (whenMinStage)
+            conditions.when_minStage = whenMinStage;
+        if (whenMinGovernance)
+            conditions.when_minGovernance = whenMinGovernance;
+        const hasConditions = Object.keys(conditions).length > 0;
+        rules.push({ name, description, scope, autoApply, body, sourcePath: filePath, targets: targets?.length ? targets : undefined, level: level || undefined, conditions: hasConditions ? conditions : undefined });
+    }
+    return rules.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Read machine-local personal rules from .productbrain/.local/rules/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned rule has persist: 'local' set, preventing projection to committed adapter files.
+ */
+export function readPersonalLayer(productbrainDir) {
+    const localRulesDir = join(productbrainDir, '.local', 'rules');
+    if (!existsSync(localRulesDir))
+        return [];
+    const files = readdirSync(localRulesDir).filter((f) => f.endsWith('.md'));
+    const rules = [];
+    for (const file of files) {
+        const filePath = join(localRulesDir, file);
+        const raw = readFileSync(filePath, 'utf8');
+        const { fields, arrayFields, body } = parseFrontmatter(raw);
+        const name = fields.get('name') ?? basename(file, '.md');
+        const description = fields.get('description') ?? '';
+        const scope = fields.get('scope');
+        const autoApply = fields.get('autoApply') === 'true';
+        const targets = arrayFields.get('targets');
+        const level = fields.get('level');
+        const conditions = {};
+        const whenStack = fields.get('when_stack');
+        const whenMinStage = fields.get('when_minStage');
+        const whenMinGovernance = fields.get('when_minGovernance');
+        if (whenStack)
+            conditions.when_stack = whenStack;
+        if (whenMinStage)
+            conditions.when_minStage = whenMinStage;
+        if (whenMinGovernance)
+            conditions.when_minGovernance = whenMinGovernance;
+        const hasConditions = Object.keys(conditions).length > 0;
+        rules.push({
+            name,
+            description,
+            scope,
+            autoApply,
+            body,
+            sourcePath: filePath,
+            targets: targets?.length ? targets : undefined,
+            level: level || undefined,
+            conditions: hasConditions ? conditions : undefined,
+            persist: 'local',
+        });
     }
     return rules.sort((a, b) => a.name.localeCompare(b.name));
 }
+/**
+ * Read machine-local personal skills from .productbrain/.local/skills/.
+ * Returns [] when the directory is absent — no-op when personal layer is not set up.
+ * Every returned skill has persist: 'local' set, preventing projection to committed adapter files.
+ */
+export function readPersonalSkillsLayer(productbrainDir) {
+    const localSkillsDir = join(productbrainDir, '.local', 'skills');
+    if (!existsSync(localSkillsDir))
+        return [];
+    const files = readdirSync(localSkillsDir).filter((f) => f.endsWith('.md'));
+    const skills = [];
+    for (const file of files) {
+        const filePath = join(localSkillsDir, file);
+        const raw = readFileSync(filePath, 'utf8');
+        const { fields, arrayFields, body } = parseFrontmatter(raw);
+        const name = fields.get('name') ?? basename(file, '.md');
+        const description = fields.get('description') ?? '';
+        const triggers = arrayFields.get('triggers') ?? [];
+        const targets = arrayFields.get('targets');
+        const level = fields.get('level');
+        const conditions = {};
+        const whenStack = fields.get('when_stack');
+        const whenMinStage = fields.get('when_minStage');
+        const whenMinGovernance = fields.get('when_minGovernance');
+        if (whenStack)
+            conditions.when_stack = whenStack;
+        if (whenMinStage)
+            conditions.when_minStage = whenMinStage;
+        if (whenMinGovernance)
+            conditions.when_minGovernance = whenMinGovernance;
+        const hasConditions = Object.keys(conditions).length > 0;
+        skills.push({
+            name,
+            description,
+            triggers,
+            body,
+            sourcePath: filePath,
+            targets: targets?.length ? targets : undefined,
+            level: level || undefined,
+            conditions: hasConditions ? conditions : undefined,
+            persist: 'local',
+        });
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
 // ── Transport section stripping ───────────────────────────────────────
 /**
  * Strip transport-conditional sections from a skill body.
@@ -149,7 +380,7 @@ export function stripTransportSections(body, target) {
  * Generate a Cursor SKILL.md from a canonical skill.
  * Cursor expects: name, description (with triggers embedded).
  */
-export function generateCursorSkill(skill) {
+export function generateCursorSkill(skill, profile) {
     // Cursor puts trigger phrases in the description field
     const triggerLine = skill.triggers.length > 0
         ? `  Use when the user says ${skill.triggers.map((t) => `"${t}"`).join(', ')}.`
@@ -174,26 +405,162 @@ ${body}`;
  * Generate a Cursor .mdc rule from a canonical rule.
  * Cursor expects: description, globs, alwaysApply.
  */
-export function generateCursorRule(rule) {
+export function generateCursorRule(rule, profile) {
     // Replace canonical paths with Cursor paths in body
     const body = rule.body
         .replace(/\.productbrain\/rules\/(\S+)\.md/g, '.cursor/rules/$1.mdc')
         .replace(/\.productbrain\/skills\/(\S+)\.md/g, '.cursor/skills/$1/SKILL.md');
     return `---
 description: ${rule.description}
-globs: ${rule.scope ?? ''}
-alwaysApply: ${rule.autoApply}
+globs: ${rule.scope || ''}
+alwaysApply: ${!rule.scope && rule.autoApply}
 ---
 <!-- ${MARKER} — source: .productbrain/rules/${rule.name}.md -->
 
 ${body}`;
 }
+// ── Codex generators ───────────────────────────────────────────────────
+/**
+ * Apply batch-mode transformations to a skill body (DEC-283).
+ *
+ * Skills describe WHAT (intent). This generator produces HOW (batch-appropriate
+ * instructions). We transform interactive patterns without gutting the skill's
+ * logical structure and purpose.
+ *
+ * Transformations applied:
+ * 1. Strip sub-agent spawn patterns → inline steps
+ * 2. Strip user confirmation gates → autonomous proceed
+ * 3. Strip streaming/interactive references
+ * 4. Add batch governance header after first `#` heading
+ */
+export function applyBatchTransformations(body) {
+    // Split into fenced code blocks vs prose so transforms only apply to prose.
+    // Fenced blocks (``` or ~~~) may contain examples of interactive patterns
+    // that must be preserved verbatim.
+    const segments = body.split(/(^```[^\n]*\n[\s\S]*?^```\s*$|^~~~[^\n]*\n[\s\S]*?^~~~\s*$)/m);
+    let result = segments
+        .map((segment, i) => {
+        // Odd indices are fenced code blocks — pass through unchanged
+        if (i % 2 === 1)
+            return segment;
+        return applyProseTransformations(segment);
+    })
+        .join('');
+    // 4. Add batch governance header after the first `#` heading line
+    const batchHeader = '> Batch execution mode: This skill runs autonomously without interactive gates. Decisions are logged, not prompted.';
+    result = result.replace(/^(#\s+[^\n]+)(\n)/m, `$1$2\n${batchHeader}\n`);
+    return result;
+}
+/** Apply interactive-pattern transforms to a prose segment (not inside code fences). */
+function applyProseTransformations(text) {
+    let result = text;
+    // 1. Sub-agent spawn patterns — lines that dispatch to sub-agents or fresh conversations
+    result = result.replace(/^.*\b(spawn\s+(a\s+)?(sub-agent|build\s+sub-agent|review\s+sub-agent|judge|system\s+verification\s+agent)|Agent\s+tool\s+dispatch|fresh\s+conversation\s+handoff|open\s+a\s+(new|fresh)\s+(conversation|chat)|start\s+a\s+(new|fresh)\s+(conversation|chat))\b.*$/gim, 'Execute as inline steps within this session.');
+    // 2. User confirmation gates — lines that halt for human input
+    result = result.replace(/^.*\b(ask\s+the\s+(user|human)|wait\s+for\s+(user\s+)?input|present\s+gate\s+to\s+(the\s+)?user|stop\s+and\s+ask|pause\s+and\s+ask|get\s+user\s+confirmation|awaiting\s+your\s+feedback|wait\s+for\s+(human|user)\s+(sign-?off|approval|input))\b.*$/gim, 'Proceed autonomously. Log decision rationale.');
+    // 3. Streaming / persistent-connection references
+    result = result.replace(/^.*\b(real-time\s+feedback|streaming\s+output|interactive\s+mcp\s+tool\s+calls?\s+that\s+assume\s+a\s+persistent\s+connection)\b.*$/gim, '');
+    return result;
+}
+/**
+ * Generate a Codex skill projection from a canonical skill.
+ * This is a repo-local markdown projection, not a separate authoring source.
+ *
+ * When profile.executionModel === 'batch', batch transformations are applied
+ * AFTER transport stripping and path replacement (DEC-283).
+ */
+export function generateCodexSkill(skill, profile) {
+    const triggerLine = skill.triggers.length > 0
+        ? `\n\n**Triggers:** ${skill.triggers.map((t) => `\`${t}\``).join(', ')}`
+        : '';
+    const stripped = stripTransportSections(skill.body, 'codex');
+    const pathReplaced = stripped
+        .replace(/\.productbrain\/skills\/(\S+)\.md/g, '.codex/skills/$1.md');
+    const body = profile?.executionModel === 'batch'
+        ? applyBatchTransformations(pathReplaced)
+        : pathReplaced;
+    return `<!-- ${MARKER} — source: .productbrain/skills/${skill.name}.md -->
+
+# ${skill.name}
+
+${skill.description}${triggerLine}
+
+${body}`;
+}
+/**
+ * Generate a Codex skill index/router file.
+ * AGENTS.md can point here so Codex has one obvious place to find available workflows.
+ */
+export function generateCodexSkillIndex(skills) {
+    const primarySkills = skills.filter((skill) => {
+        const lower = skill.name.toLowerCase();
+        return lower !== 'learnings-template' && !lower.endsWith('-learnings');
+    });
+    if (primarySkills.length === 0) {
+        return `<!-- ${MARKER} — source: generated from .productbrain/skills/*.md -->
+
+# Product Brain Skills for Codex
+
+No Product Brain skills are currently projected for Codex in this repo.
+`;
+    }
+    const blocks = primarySkills.map((skill) => {
+        const triggerText = skill.triggers.length > 0
+            ? `Triggers: ${skill.triggers.map((t) => `\`${t}\``).join(', ')}`
+            : 'Triggers: none declared';
+        return `## ${skill.name}
+
+${skill.description}
+
+${triggerText}
+
+Read: \`.codex/skills/${skill.name}.md\``;
+    });
+    return `<!-- ${MARKER} — source: generated from .productbrain/skills/*.md -->
+
+# Product Brain Skills for Codex
+
+When the task matches one of these workflows, read the linked skill file first and follow its protocol.
+Maintenance companions like \`*-learnings\` and \`LEARNINGS-TEMPLATE\` are still projected on disk, but hidden from this index so the primary workflows stay easy to scan.
+
+${blocks.join('\n\n')}`;
+}
+const CODEX_DEAD_REFERENCE_PATTERNS = [
+    { pattern: /\bpb\s+(session|orient|get|capture|search|update|handshake|context|constellation)\b/, label: 'pb CLI command' },
+    { pattern: /\bsub-agent\b/i, label: 'sub-agent reference' },
+    { pattern: /\bAgent\s+tool\b/, label: 'Agent tool reference' },
+    { pattern: /\bkernelCall\b/, label: 'kernelCall reference' },
+    { pattern: /\bpb\s+session\s+(start|close)\b/, label: 'pb session lifecycle' },
+];
+/**
+ * Validate Codex-projected skills for references to capabilities Codex cannot execute.
+ * Scans the transport-stripped body (so claude-only blocks don't false-positive).
+ */
+export function validateCodexSkills(skills) {
+    const warnings = [];
+    for (const skill of skills) {
+        const stripped = stripTransportSections(skill.body, 'codex');
+        const lines = stripped.split('\n');
+        for (const line of lines) {
+            for (const { pattern, label } of CODEX_DEAD_REFERENCE_PATTERNS) {
+                if (pattern.test(line)) {
+                    warnings.push({
+                        skillName: skill.name,
+                        pattern: label,
+                        line: line.trim().slice(0, 80),
+                    });
+                }
+            }
+        }
+    }
+    return warnings;
+}
 // ── Claude Code generators ────────────────────────────────────────────
 /**
  * Generate a Claude Code .md rule from a canonical rule.
  * Claude Code expects: description, optional paths (array).
  */
-export function generateClaudeRule(rule) {
+export function generateClaudeRule(rule, profile) {
     // Replace canonical paths with Claude Code paths in body
     const body = rule.body
         .replace(/\.productbrain\/rules\/(\S+)\.md/g, '.claude/rules/$1.md')
@@ -215,7 +582,7 @@ ${body}`;
  * Generate a Claude Code skill-router.md — imperative skill activation rule.
  * Loaded automatically by Claude Code via .claude/rules/ with no paths (always active).
  */
-export function generateClaudeSkillRouter(skills) {
+export function generateClaudeSkillRouter(skills, profile) {
     if (skills.length === 0)
         return '';
     const triggerBlocks = skills.map((skill) => {