opengstack 0.13.10 → 0.14.2

package/scripts/resolvers/codex-helpers.ts

@@ -0,0 +1,133 @@
+import type { Host } from './types';
+
+const OPENAI_SHORT_DESCRIPTION_LIMIT = 120;
+
+export function extractNameAndDescription(content: string): { name: string; description: string } {
+ const fmStart = content.indexOf('---\n');
+ if (fmStart !== 0) return { name: '', description: '' };
+ const fmEnd = content.indexOf('\n---', fmStart + 4);
+ if (fmEnd === -1) return { name: '', description: '' };
+
+ const frontmatter = content.slice(fmStart + 4, fmEnd);
+ const nameMatch = frontmatter.match(/^name:\s*(.+)$/m);
+ const name = nameMatch ? nameMatch[1].trim() : '';
+
+ let description = '';
+ const lines = frontmatter.split('\n');
+ let inDescription = false;
+ const descLines: string[] = [];
+ for (const line of lines) {
+ if (line.match(/^description:\s*\|?\s*$/)) {
+ inDescription = true;
+ continue;
+ }
+ if (line.match(/^description:\s*\S/)) {
+ description = line.replace(/^description:\s*/, '').trim();
+ break;
+ }
+ if (inDescription) {
+ if (line === '' || line.match(/^\s/)) {
+ descLines.push(line.replace(/^ /, ''));
+ } else {
+ break;
+ }
+ }
+ }
+ if (descLines.length > 0) {
+ description = descLines.join('\n').trim();
+ }
+
+ return { name, description };
+}
+
+export function condenseOpenAIShortDescription(description: string): string {
+ const firstParagraph = description.split(/\n\s*\n/)[0] || description;
+ const collapsed = firstParagraph.replace(/\s+/g, ' ').trim();
+ if (collapsed.length <= OPENAI_SHORT_DESCRIPTION_LIMIT) return collapsed;
+
+ const truncated = collapsed.slice(0, OPENAI_SHORT_DESCRIPTION_LIMIT - 3);
+ const lastSpace = truncated.lastIndexOf(' ');
+ const safe = lastSpace > 40 ? truncated.slice(0, lastSpace) : truncated;
+ return `${safe}...`;
+}
+
+export function generateOpenAIYaml(displayName: string, shortDescription: string): string {
+ return `interface:
+ display_name: ${JSON.stringify(displayName)}
+ short_description: ${JSON.stringify(shortDescription)}
+ default_prompt: ${JSON.stringify(`Use ${displayName} for this task.`)}
+policy:
+ allow_implicit_invocation: true
+`;
+}
+
+/** Compute skill name for external hosts (Codex, Factory, etc.) */
+export function externalSkillName(skillDir: string): string {
+ if (skillDir === '.' || skillDir === '') return 'OpenGStack';
+ // Don't double-prefix: opengstack-upgrade → opengstack-upgrade (not opengstack-opengstack-upgrade)
+ if (skillDir.startsWith('opengstack-')) return skillDir;
+ return `opengstack-${skillDir}`;
+}
+
+/**
+ * Transform frontmatter for Codex: keep only name + description.
+ * Strips allowed-tools, hooks, version, and all other fields.
+ * Handles multiline block scalar descriptions (YAML | syntax).
+ */
+export function transformFrontmatter(content: string, host: Host): string {
+ if (host === 'claude') return content;
+
+ // Find frontmatter boundaries
+ const fmStart = content.indexOf('---\n');
+ if (fmStart !== 0) return content; // frontmatter must be at the start
+ const fmEnd = content.indexOf('\n---', fmStart + 4);
+ if (fmEnd === -1) return content;
+
+ const body = content.slice(fmEnd + 4); // includes the leading \n after ---
+ const { name, description } = extractNameAndDescription(content);
+
+ // Codex 1024-char description limit — fail build, don't ship broken skills
+ const MAX_DESC = 1024;
+ if (description.length > MAX_DESC) {
+ throw new Error(
+ `Codex description for "${name}" is ${description.length} chars (max ${MAX_DESC}). ` +
+ `Compress the description in the .tmpl file.`
+ );
+ }
+
+ // Re-emit Codex frontmatter (name + description only)
+ const indentedDesc = description.split('\n').map(l => ` ${l}`).join('\n');
+ const codexFm = `---\nname: ${name}\ndescription: |\n${indentedDesc}\n---`;
+ return codexFm + body;
+}
+
+/**
+ * Extract hook descriptions from frontmatter for inline safety prose.
+ * Returns a description of what the hooks do, or null if no hooks.
+ */
+export function extractHookSafetyProse(tmplContent: string): string | null {
+ if (!tmplContent.match(/^hooks:/m)) return null;
+
+ // Parse the hook matchers to build a human-readable safety description
+ const matchers: string[] = [];
+ const matcherRegex = /matcher:\s*"(\w+)"/g;
+ let m;
+ while ((m = matcherRegex.exec(tmplContent)) !== null) {
+ if (!matchers.includes(m[1])) matchers.push(m[1]);
+ }
+
+ if (matchers.length === 0) return null;
+
+ // Build safety prose based on what tools are hooked
+ const toolDescriptions: Record<string, string> = {
+ Bash: 'check bash commands for destructive operations (rm -rf, DROP TABLE, force-push, git reset --hard, etc.) before execution',
+ Edit: 'verify file edits are within the allowed scope boundary before applying',
+ Write: 'verify file writes are within the allowed scope boundary before applying',
+ };
+
+ const safetyChecks = matchers
+ .map(t => toolDescriptions[t] || `check ${t} operations for safety`)
+ .join(', and ');
+
+ return `> **Safety Advisory:** This skill includes safety checks that ${safetyChecks}. When using this skill, always pause and verify before executing potentially destructive operations. If uncertain about a command's safety, ask the user for confirmation before proceeding.`;
+}

package/scripts/resolvers/composition.ts

@@ -0,0 +1,48 @@
+import type { TemplateContext } from './types';
+
+/**
+ * {{INVOKE_SKILL:skill-name}} — emits prose instructing Claude to read
+ * another skill's SKILL.md and follow it, skipping preamble sections.
+ *
+ * Supports optional skip= parameter for additional sections to skip:
+ * {{INVOKE_SKILL:plan-ceo-review:skip=Outside Voice,Design Outside Voices}}
+ */
+export function generateInvokeSkill(ctx: TemplateContext, args?: string[]): string {
+ const skillName = args?.[0];
+ if (!skillName || skillName === '') {
+ throw new Error('{{INVOKE_SKILL}} requires a skill name, e.g. {{INVOKE_SKILL:plan-ceo-review}}');
+ }
+
+ // Parse optional skip= parameter from args[1+]
+ const extraSkips = (args?.slice(1) || [])
+ .filter(a => a.startsWith('skip='))
+ .flatMap(a => a.slice(5).split(','))
+ .map(s => s.trim())
+ .filter(Boolean);
+
+ const DEFAULT_SKIPS = [
+ 'Preamble (run first)',
+ 'AskUserQuestion Format',
+ 'Completeness Principle — Boil the Lake',
+ 'Search Before Building',
+ 'Contributor Mode',
+ 'Completion Status Protocol',
+ 
+ 'Step 0: Detect platform and base branch',
+ 'Review Readiness Dashboard',
+ 'Plan File Review Report',
+ 'Prerequisite Skill Offer',
+ 'Plan Status Footer',
+ ];
+
+ const allSkips = [...DEFAULT_SKIPS, ...extraSkips];
+
+ return `Read the \`/${skillName}\` skill file at \`${ctx.paths.skillRoot}/${skillName}/SKILL.md\` using the Read tool.
+
+**If unreadable:** Skip with "Could not load /${skillName} — skipping." and continue.
+
+Follow its instructions from top to bottom, **skipping these sections** (already handled by the parent skill):
+${allSkips.map(s => `- ${s}`).join('\n')}
+
+Execute every other section at full depth. When the loaded skill's instructions are complete, continue with the next step below.`;
+}

package/scripts/resolvers/confidence.ts

@@ -0,0 +1,37 @@
+/**
+ * Confidence calibration resolver
+ *
+ * Adds confidence scoring rubric to review-producing skills.
+ * Every finding includes a 1-10 score that gates display:
+ * 7+: show normally
+ * 5-6: show with caveat
+ * <5: suppress from main report
+ */
+import type { TemplateContext } from './types';
+
+export function generateConfidenceCalibration(_ctx: TemplateContext): string {
+ return `## Confidence Calibration
+
+Every finding MUST include a confidence score (1-10):
+
+| Score | Meaning | Display rule |
+|-------|---------|-------------|
+| 9-10 | Verified by reading specific code. Concrete bug or exploit demonstrated. | Show normally |
+| 7-8 | High confidence pattern match. Very likely correct. | Show normally |
+| 5-6 | Moderate. Could be a false positive. | Show with caveat: "Medium confidence, verify this is actually an issue" |
+| 3-4 | Low confidence. Pattern is suspicious but may be fine. | Suppress from main report. Include in appendix only. |
+| 1-2 | Speculation. | Only report if severity would be P0. |
+
+**Finding format:**
+
+\\\`[SEVERITY] (confidence: N/10) file:line — description\\\`
+
+Example:
+\\\`[P1] (confidence: 9/10) app/models/user.rb:42 — SQL injection via string interpolation in where clause\\\`
+\\\`[P2] (confidence: 5/10) app/controllers/api/v1/users_controller.rb:18 — Possible N+1 query, verify with production logs\\\`
+
+**Calibration learning:** If you report a finding with confidence < 7 and the user
+confirms it IS a real issue, that is a calibration event. Your initial confidence was
+too low. Log the corrected pattern as a learning so future reviews catch it with
+higher confidence.`;
+}

package/scripts/resolvers/constants.ts

@@ -0,0 +1,50 @@
+// ─── Shared Design Constants ────────────────────────────────
+
+/** OpenGStack's 10 AI slop anti-patterns — shared between DESIGN_METHODOLOGY and DESIGN_HARD_RULES */
+export const AI_SLOP_BLACKLIST = [
+ 'Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes',
+ '**The 3-column feature grid:** icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.',
+ 'Icons in colored circles as section decoration (SaaS starter template look)',
+ 'Centered everything (`text-align: center` on all headings, descriptions, cards)',
+ 'Uniform bubbly border-radius on every element (same large radius on everything)',
+ 'Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)',
+ 'Emoji as design elements (rockets in headings, emoji as bullet points)',
+ 'Colored left-border on cards (`border-left: 3px solid <accent>`)',
+ 'Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")',
+ 'Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)',
+];
+
+/** OpenAI hard rejection criteria (from "Designing Delightful Frontends with GPT-5.4", Mar 2026) */
+export const OPENAI_HARD_REJECTIONS = [
+ 'Generic SaaS card grid as first impression',
+ 'Beautiful image with weak brand',
+ 'Strong headline with no clear action',
+ 'Busy imagery behind text',
+ 'Sections repeating same mood statement',
+ 'Carousel with no narrative purpose',
+ 'App UI made of stacked cards instead of layout',
+];
+
+/** OpenAI litmus checks — 7 yes/no tests for cross-model consensus scoring */
+export const OPENAI_LITMUS_CHECKS = [
+ 'Brand/product unmistakable in first screen?',
+ 'One strong visual anchor present?',
+ 'Page understandable by scanning headlines only?',
+ 'Each section has one job?',
+ 'Are cards actually necessary?',
+ 'Does motion improve hierarchy or atmosphere?',
+ 'Would design feel premium with all decorative shadows removed?',
+];
+
+/**
+ * Shared Codex error handling block for resolver output.
+ * Used by ADVERSARIAL_STEP, CODEX_PLAN_REVIEW, CODEX_SECOND_OPINION,
+ * DESIGN_OUTSIDE_VOICES, DESIGN_REVIEW_LITE, DESIGN_SKETCH.
+ */
+export function codexErrorHandling(feature: string): string {
+ return `**Error handling:** All errors are non-blocking — the ${feature} is informational.
+- Auth failure (stderr contains "auth", "login", "unauthorized"): note and skip
+- Timeout: note timeout duration and skip
+- Empty response: note and skip
+On any error: continue — ${feature} is informational, not a gate.`;
+}