@haposoft/cafekit 0.16.6 → 0.18.0

package/src/claude/skills/ui-ux-pro-max/SKILL.md

@@ -2,7 +2,7 @@
 name: cf:ui-ux-pro-max
 description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
 user-invocable: true
-when_to_use: "Invoke to choose colors, fonts, layout, and design systems."
+when_to_use: "Invoke to look up color palettes, font pairings, product-type styles, or UX guidelines; to build or review a screen use cf:ui-ux."
 category: frontend
 keywords: [ui, ux, design-system, layout]
 metadata:

package/src/claude/status.cjs

@@ -2,7 +2,7 @@
 'use strict';
 
 /**
- * Custom Claude Code statusline for Node.js - Multi-line Edition
+ * Custom Claude Code statusline for Node.js - one-line default
  * Cross-platform support: Windows, macOS, Linux
  * Features: ANSI colors, tool/agent/todo tracking, context window, session timer
  * No external dependencies - uses only Node.js built-in modules
@@ -26,10 +26,6 @@ const { getGitInfo } = require('./hooks/lib/git.cjs');
 // ratio so 1M-context models are not treated as if they were 200k.
 const AUTOCOMPACT_BUFFER_RATIO = 0.225;
 
-// Usage cache freshness gate: a cache older than this hides the quota area
-// instead of rendering stale numbers.
-const USAGE_CACHE_TTL_MS = 300000;
-
 /**
  * Expand home directory to ~
  */
@@ -104,7 +100,7 @@ async function readStdin() {
  * @returns {string|null} Formatted usage string or null if unavailable
  */
 function buildUsageString(ctx) {
-  if (!ctx.sessionText || ctx.sessionText === 'N/A') return null;
+  if (!ctx.sessionText) return null;
   let str = ctx.sessionText.replace(' until reset', ' left');
   if (ctx.usagePercent != null) str += ` (${Math.round(ctx.usagePercent)}%)`;
   return str;
@@ -130,77 +126,115 @@ function buildBranchPart(ctx) {
   return branchPart;
 }
 
-function renderSessionLines(ctx) {
-  const lines = [];
-  const termWidth = getTerminalWidth();
-  const threshold = Math.floor(termWidth * 0.85);
+// Default session line: one row of single-width symbols, each value labelled by
+// its glyph so the line stays short and every number says what it measures.
+//   ◆ model (effort) ϟfast ✱thinking  ◔ context%  ⧗ 5h-quota% reset  ◷ weekly%  ⎇ branch ●changed ↑ahead ↓behind  ± +added/-removed  ⏱ session  ↻ cache-hit%
+
+/** Quarter-circle glyph that fills with the percentage. */
+function fillGlyph(percent) {
+  if (percent >= 88) return '●';
+  if (percent >= 63) return '◕';
+  if (percent >= 38) return '◑';
+  if (percent >= 13) return '◔';
+  return '○';
+}
 
-  // Build all atomic parts for flexible composition (no colors on static text)
-  const dirPart = `📁 ${ctx.currentDir}`;
-  const branchPart = buildBranchPart(ctx);
+/** Same thresholds as the context bar; plain text when colours are off. */
+function tintPercent(percent, text) {
+  if (percent >= 85) return red(text);
+  if (percent >= 70) return yellow(text);
+  return green(text);
+}
 
-  // Active plan indicator (disabled for now - code preserved)
-  // const planPart = ctx.activePlan ? `📋 ${ctx.activePlan}` : '';
-  const planPart = '';
+/** "2h 48m until reset" → "2h48m"; anything else → null. */
+function shortReset(sessionText) {
+  const match = /^(\d+)h (\d+)m/.exec(sessionText || '');
+  return match ? `${match[1]}h${match[2]}m` : null;
+}
 
-  // Combined location (dir + branch + plan)
-  let locationPart = branchPart ? `${dirPart}  ${branchPart}` : dirPart;
-  if (planPart) locationPart += `  ${planPart}`;
+/** 28147114 → "7h49m"; under an hour → "12m". */
+function formatDuration(ms) {
+  const minutes = Math.floor(ms / 60000);
+  const hours = Math.floor(minutes / 60);
+  return hours > 0 ? `${hours}h${String(minutes % 60).padStart(2, '0')}m` : `${minutes}m`;
+}
+
+/** "#80✓" approved, "#80✗" changes requested, "#80" pending, dim "#80" draft; "!80" for a GitLab MR. */
+function formatPr(pr) {
+  const label = `${pr.kind === 'mr' ? '!' : '#'}${pr.number}`;
+  if (pr.review_state === 'approved') return `${label}${green('✓')}`;
+  if (pr.review_state === 'changes_requested') return `${label}${red('✗')}`;
+  if (pr.review_state === 'draft') return dim(label);
+  return label;
+}
+
+/**
+ * Parts of the default line in display order. `drop` ranks what goes first
+ * when the terminal is too narrow (higher drops earlier); 0 never drops.
+ */
+function buildLineParts(ctx, { minimal = false } = {}) {
+  let model = `◆ ${ctx.modelName}`;
+  if (ctx.effortLevel) model += ` ${dim(`(${ctx.effortLevel})`)}`;
+  const flags = `${ctx.fastMode ? 'ϟ' : ''}${ctx.thinking ? '✱' : ''}`;
+  if (flags) model += ` ${flags}`;
+  const parts = [{ text: model, drop: 0 }];
 
-  // Build session part: 🤖 model  contextBar%  ⌛ time left (usage%)
-  let sessionPart = `🤖 ${ctx.modelName}`;
   if (ctx.contextPercent > 0) {
-    sessionPart += `  ${coloredBar(ctx.contextPercent, 12)} ${ctx.contextPercent}%`;
+    parts.push({ text: tintPercent(ctx.contextPercent, `${fillGlyph(ctx.contextPercent)} ${ctx.contextPercent}%`), drop: 0 });
   }
-  // Add usage/reset info to session part (stays on line 1 with model - Claude Code only reads line 1)
-  const usageStr = buildUsageString(ctx);
-  if (usageStr) {
-    sessionPart += `  ⌛ ${usageStr.replace(/\)$/, ' used)')}`;
-    if (ctx.weeklyText) sessionPart += `  ${ctx.weeklyText}`;
+
+  if (!minimal && ctx.usagePercent != null) {
+    const pct = Math.round(ctx.usagePercent);
+    const reset = shortReset(ctx.sessionText);
+    parts.push({ text: `⧗ ${tintPercent(pct, `${pct}%`)}${reset ? ` ${dim(reset)}` : ''}`, drop: 2 });
   }
 
-  // Build stats part (only lines changed now)
-  const statsItems = [];
-  // if (ctx.costText) statsItems.push(`💵 ${ctx.costText.replace(/(\.\d{2})\d+/, '$1')}`);
-  if (ctx.linesAdded > 0 || ctx.linesRemoved > 0) {
-    statsItems.push(`📝 ${green(`+${ctx.linesAdded}`)} ${red(`-${ctx.linesRemoved}`)}`);
+  if (!minimal && ctx.weeklyPercent != null) {
+    parts.push({ text: `◷ ${tintPercent(ctx.weeklyPercent, `${ctx.weeklyPercent}%`)}`, drop: 3 });
   }
-  const statsPart = statsItems.join('  ');
-
-  // Calculate lengths for layout decisions
-  const locationLen = visibleLength(locationPart);
-  const sessionLen = visibleLength(sessionPart);
-  const statsLen = visibleLength(statsPart);
-
-  // Layout priority: SESSION FIRST (Claude Code only reads line 1)
-  // Line 1: model + context + usage (most important for Claude Code)
-  // Line 2+: location, git, stats
-  const allOneLine = `${sessionPart}  ${locationPart}  ${statsPart}`;
-  const sessionLocation = `${sessionPart}  ${locationPart}`;
-  const sessionStats = `${sessionPart}  ${statsPart}`;
-
-  if (visibleLength(allOneLine) <= threshold && statsLen > 0) {
-    // Ultra-wide: everything on one line (session first)
-    lines.push(allOneLine);
-  } else if (visibleLength(sessionLocation) <= threshold) {
-    // Wide: session+location on line 1 | stats on line 2
-    lines.push(sessionLocation);
-    if (statsLen > 0) lines.push(statsPart);
-  } else if (sessionLen <= threshold) {
-    // Medium: session on line 1 | location on line 2 | stats on line 3
-    lines.push(sessionPart);
-    lines.push(locationPart);
-    if (statsLen > 0) lines.push(statsPart);
-  } else {
-    // Narrow: session | dir | branch | stats (each on own line)
-    lines.push(sessionPart);
-    lines.push(dirPart);
-    if (branchPart) lines.push(branchPart);
-    if (planPart) lines.push(planPart);
-    if (statsLen > 0) lines.push(statsPart);
+
+  if (ctx.gitBranch) {
+    let git = `⎇ ${ctx.gitBranch}`;
+    if (!minimal) {
+      const changed = ctx.gitUnstaged + ctx.gitStaged;
+      if (changed > 0) git += ` ${yellow(`●${changed}`)}`;
+      if (ctx.gitAhead > 0) git += ` ↑${ctx.gitAhead}`;
+      if (ctx.gitBehind > 0) git += ` ↓${ctx.gitBehind}`;
+      if (ctx.pr) git += ` ${formatPr(ctx.pr)}`;
+      if (ctx.inWorktree) git += ' ⊟';
+    }
+    parts.push({ text: git, drop: 1 });
   }
 
-  return lines;
+  if (!minimal && (ctx.linesAdded > 0 || ctx.linesRemoved > 0)) {
+    parts.push({ text: `± ${green(`+${ctx.linesAdded}`)}/${red(`-${ctx.linesRemoved}`)}`, drop: 4 });
+  }
+
+  if (!minimal && ctx.durationMs >= 60000) {
+    parts.push({ text: `⏱ ${formatDuration(ctx.durationMs)}`, drop: 5 });
+  }
+
+  if (!minimal && ctx.cacheHitRatio != null) {
+    const pct = Math.round(ctx.cacheHitRatio * 100);
+    const tinted = pct < 50 ? red(`${pct}%`) : pct < 80 ? yellow(`${pct}%`) : green(`${pct}%`);
+    parts.push({ text: `↻ ${tinted}`, drop: 6 });
+  }
+
+  return parts;
+}
+
+/** Join parts, dropping the highest-ranked ones until the line fits the terminal. */
+function fitLine(parts) {
+  const width = getTerminalWidth() - 2;
+  const kept = [...parts];
+  const join = () => kept.map((part) => part.text).join('  ');
+  while (visibleLength(join()) > width) {
+    const candidates = kept.filter((part) => part.drop > 0);
+    if (candidates.length === 0) break;
+    const victim = candidates.reduce((a, b) => (b.drop > a.drop ? b : a));
+    kept.splice(kept.indexOf(victim), 1);
+  }
+  return join();
 }
 
 /**
@@ -309,52 +343,21 @@ function renderTodosLine(transcript) {
   return `${yellow('▸')} ${display} ${dim(`(${completedCount} done, ${pendingCount} pending)`)}`;
 }
 
-/**
- * Render minimal mode - single line with emojis, no progress bar
- * Format: "🤖 opus 4.5  🔋 50%  ⏰ 2h 16m (38%)  🌿 branch  📁 ~/path"
- */
+/** minimal mode: model, context and branch only. */
 function renderMinimal(ctx) {
-  const parts = [`🤖 ${ctx.modelName}`];
-  if (ctx.contextPercent > 0) {
-    const batteryIcon = ctx.contextPercent > 70 ? red('🔋') : '🔋';
-    parts.push(`${batteryIcon} ${ctx.contextPercent}%`);
-  }
-  const usageStr = buildUsageString(ctx);
-  if (usageStr) parts.push(`⏰ ${usageStr}${ctx.weeklyText ? `  ${ctx.weeklyText}` : ''}`);
-  if (ctx.gitBranch) parts.push(`🌿 ${ctx.gitBranch}`);
-  parts.push(`📁 ${ctx.currentDir}`);
-  console.log(parts.join('  '));
+  writeStyledLines([fitLine(buildLineParts(ctx, { minimal: true }))]);
 }
 
-/**
- * Render compact mode - 2 lines: session info + location (branch + dir)
- */
+/** compact mode: the default line without the agent and todo lines. */
 function renderCompact(ctx) {
-  // Line 1: Session info (model + context + usage)
-  let line1 = `🤖 ${ctx.modelName}`;
-  if (ctx.contextPercent > 0) {
-    line1 += `  ${coloredBar(ctx.contextPercent, 12)} ${ctx.contextPercent}%`;
-  }
-  const usageStr = buildUsageString(ctx);
-  if (usageStr) line1 += `  ⌛ ${usageStr}${ctx.weeklyText ? `  ${ctx.weeklyText}` : ''}`;
-  console.log(line1.replace(/ /g, '\u00A0'));
-
-  // Line 2: Location (branch + directory)
-  let line2 = `📁 ${ctx.currentDir}`;
-  if (ctx.gitBranch) line2 += `  🌿 ${ctx.gitBranch}`;
-  console.log(line2.replace(/ /g, '\u00A0'));
+  render(ctx, true);
 }
 
 /**
- * Main render function - outputs all lines
- * Falls back to single line if multi-line fails
+ * full mode: the default line, then agent and todo lines only while they exist.
  */
 function render(ctx, singleLineMode = false) {
-  const lines = [];
-
-  // Session lines (cleaner multi-line layout)
-  const sessionLines = renderSessionLines(ctx);
-  lines.push(...sessionLines);
+  const lines = [fitLine(buildLineParts(ctx))];
 
   if (!singleLineMode) {
     // Agents lines (one per agent for clarity)
@@ -463,6 +466,8 @@ async function main() {
     currentDir = expandHome(currentDir);
 
     const modelName = data.model?.display_name || 'Claude';
+    // Live /effort value; absent when the model has no effort parameter.
+    const effortLevel = typeof data.effort?.level === 'string' ? data.effort.level : '';
 
     // Git detection using batched cache
     const rawDir = data.workspace?.current_dir || data.cwd || process.cwd();
@@ -522,55 +527,39 @@ async function main() {
       } catch {}
     }
 
-    // Session timer - read actual reset time from usage limits cache
+    // Quota text, filled from the payload's rate_limits below
     let sessionText = '';
     let weeklyText = '';
+    let weeklyPercent = null;
     const transcriptPath = data.transcript_path;
 
     // Parse transcript for tools/agents/todos
     const transcript = transcriptPath ? await parseTranscript(transcriptPath) : { tools: [], agents: [], todos: [], sessionStart: null };
 
-    // Read actual reset time and utilization from usage limits cache (written by usage-context-awareness hook)
+    // Quota windows come only from Claude Code's own rate_limits, sent for Pro/Max after
+    // the session's first API response; without it the quota segments stay hidden.
     let usagePercent = null;
-    try {
-      const usageCachePath = path.join(os.tmpdir(), 'ck-usage-limits-cache.json');
-      if (fs.existsSync(usageCachePath)) {
-        const cache = JSON.parse(fs.readFileSync(usageCachePath, 'utf8'));
-
-        // Check status flag for fallback (non-OAuth scenarios)
-        const fresh = typeof cache.timestamp === 'number'
-          && Date.now() - cache.timestamp < USAGE_CACHE_TTL_MS;
-        if (cache.status === 'unavailable') {
-          sessionText = 'N/A';
-        } else if (cache.status === 'available' && fresh) {
-          const fiveHour = cache.data?.five_hour;
-          usagePercent = fiveHour?.utilization ?? null;
-          const resetAt = fiveHour?.resets_at;
-          if (resetAt) {
-            const resetTime = new Date(resetAt);
-            const remaining = Math.floor(resetTime.getTime() / 1000) - Math.floor(Date.now() / 1000);
-            if (remaining > 0 && remaining < 18000) {
-              const rh = Math.floor(remaining / 3600);
-              const rm = Math.floor((remaining % 3600) / 60);
-              sessionText = `${rh}h ${rm}m until reset`;
-            }
-          }
-          const sevenDay = cache.data?.seven_day;
-          if (sevenDay?.utilization != null) {
-            weeklyText = `wk ${Math.round(sevenDay.utilization)}%`;
-            const wkResetAt = sevenDay.resets_at;
-            if (wkResetAt) {
-              const wkRemaining = Math.floor(new Date(wkResetAt).getTime() / 1000) - Math.floor(Date.now() / 1000);
-              if (wkRemaining > 0) {
-                const wd = Math.floor(wkRemaining / 86400);
-                const wh = Math.floor((wkRemaining % 86400) / 3600);
-                weeklyText += ` (${wd}d ${wh}h)`;
-              }
-            }
-          }
+    const applyWindows = (fiveHour, sevenDay) => {
+      if (fiveHour?.percent != null) {
+        usagePercent = fiveHour.percent;
+        const remaining = Math.floor(fiveHour.resetsAtMs / 1000) - Math.floor(Date.now() / 1000);
+        if (remaining > 0 && remaining < 18000) {
+          sessionText = `${Math.floor(remaining / 3600)}h ${Math.floor((remaining % 3600) / 60)}m until reset`;
         }
       }
-    } catch {}
+      if (sevenDay?.percent != null) {
+        weeklyPercent = Math.round(sevenDay.percent);
+        weeklyText = `wk ${weeklyPercent}%`;
+        const wkRemaining = Math.floor(sevenDay.resetsAtMs / 1000) - Math.floor(Date.now() / 1000);
+        if (wkRemaining > 0) {
+          weeklyText += ` (${Math.floor(wkRemaining / 86400)}d ${Math.floor((wkRemaining % 86400) / 3600)}h)`;
+        }
+      }
+    };
+    const fromPayload = (window) => (window && typeof window.used_percentage === 'number'
+      ? { percent: window.used_percentage, resetsAtMs: Number(window.resets_at) * 1000 }
+      : null);
+    applyWindows(fromPayload(data.rate_limits?.five_hour), fromPayload(data.rate_limits?.seven_day));
 
     // Cost and lines changed
     const billingMode = env.CLAUDE_BILLING_MODE || 'api';
@@ -580,6 +569,14 @@ async function main() {
       : null;
     const linesAdded = data.cost?.total_lines_added || 0;
     const linesRemoved = data.cost?.total_lines_removed || 0;
+    const durationMs = Number(data.cost?.total_duration_ms) || 0;
+    const cacheHitRatio = data.prompt_cache?.requests > 0 && typeof data.prompt_cache.hit_ratio === 'number'
+      ? data.prompt_cache.hit_ratio
+      : null;
+    const fastMode = data.fast_mode === true;
+    const thinking = data.thinking?.enabled === true;
+    const pr = typeof data.pr?.number === 'number' ? data.pr : null;
+    const inWorktree = Boolean(data.worktree?.name || data.workspace?.git_worktree);
 
     // Config counts
     const configs = countConfigs(rawDir);
@@ -587,6 +584,7 @@ async function main() {
     // Build render context
     const ctx = {
       modelName,
+      effortLevel,
       currentDir,
       gitBranch,
       gitUnstaged,
@@ -597,10 +595,17 @@ async function main() {
       contextPercent,
       sessionText,
       weeklyText,
+      weeklyPercent,
       usagePercent,
       costText,
       linesAdded,
       linesRemoved,
+      durationMs,
+      cacheHitRatio,
+      fastMode,
+      thinking,
+      pr,
+      inWorktree,
       configs,
       transcript
     };
@@ -636,11 +641,11 @@ async function main() {
 
   } catch (err) {
     // Fallback: output minimal single line on any error
-    console.log('📁 ' + (process.cwd() || 'unknown'));
+    console.log(`◆ ${expandHome(process.cwd() || 'unknown')}`);
   }
 }
 
 main().catch(() => {
-  console.log('📁 error');
+  console.log('◆ statusline error');
   process.exit(1);
 });

package/src/codex/AGENTS.md

@@ -10,17 +10,19 @@
 - For skill selection, read `.codex/rules/skill-workflow-routing.md` and
   `.codex/rules/skill-domain-routing.md`. When capability presence is uncertain,
   run `node .codex/scripts/generate-skill-catalog.cjs --skills`; its Codex-bound
-  root is `.agents/skills`. Use `$cf-route` only for ambiguous, multi-step,
-  multi-domain, or risk-elevated work; explicit, obvious, and factual intents
-  stay direct.
+  root is `.agents/skills`. Explicit, obvious, and factual intents stay
+  direct; compose a short chain only for ambiguous, multi-step, multi-domain, or
+  risk-elevated work.
 - Consult `.codex/rules/review-audit-self-decision.md` before applying audit
   feedback, reversing a verified or user decision, or cutting scope, and
   `.codex/rules/process-management.md` whenever a task starts, reuses, or ends
   long-running processes.
+- Read `.codex/rules/state-sync.md` before changing a task `Status:` or Receipt,
+  and `.codex/rules/hook-protocols.md` when a hook blocks or asks.
 - Project hooks live in `.codex/hooks.json`; review trusted hooks with `/hooks`.
-- New Specs work uses the process-first flow. `$cf-specs` opens C1, writes
+- New Specs work uses the process-first flow. `$cf-specs` opens GATE-SCOPE, writes
   `specs/<feature>/plan.md` with flat `task-NN-*.md` files beside it, then opens
-  C2 after adversarial review. It never starts implementation.
+  GATE-REVIEW after adversarial review. It never starts implementation.
 - Start implementation only through a new explicit `$cf-develop` invocation.
   Execute one unblocked task at a time; each task has exactly one `Status:`
   field and the controller is its sole state-and-proof writer.
@@ -28,16 +30,9 @@
   requires a canonical final inline `## Receipt` with the exact command,
   `Exit: 0`, `Verification: PASS`, runtime-derived Base and Head values, and
   non-empty fenced current output.
-- At C3, show current receipts and unresolved limitations. The user decides
+- At GATE-DONE, show current receipts and unresolved limitations. The user decides
   completion; no command, review, or host state may invent approval or proof.
 
-### Legacy Specs compatibility
-
-Existing packets containing `spec.json`, nested tasks, or legacy kernel
-artifacts keep their installed adapter, `task_registry`, `semantic_model`,
-`planning_depth`, lane, `execution_tier`, machine authority, separate receipts,
-and closeout contract. Do not migrate them during unrelated process-first work.
-
 ## Codex caveats
 
 - Custom agents use snake_case names and `fork_turns: "none"` for explicit delegation.

package/src/codex/hooks/agent.cjs

@@ -26,6 +26,7 @@ try {
   const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');
   const plansPath = resolveProjectPath(projectRoot, runtime.paths?.plans, 'plans');
   const docsPath = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const specsPath = resolveProjectPath(projectRoot, runtime.paths?.specs, 'specs');
   const venv = resolveVenv(projectRoot);
   const lines = [
     `## Subagent: ${payload.agent_type || 'unknown'}`,
@@ -44,7 +45,7 @@ try {
 
   lines.push(
     '## Rules',
-    `- Plans → ${plansPath}/ | Docs → ${docsPath}/`,
+    `- Specs → ${specsPath}/ | Plans → ${plansPath}/ | Docs → ${docsPath}/`,
     '- YAGNI · KISS · DRY',
     '- Be concise. List unresolved questions at end.'
   );

package/src/codex/hooks/lib/spec-receipt.cjs

@@ -99,6 +99,10 @@ function checkFeatureReceipt(featureDir, runtimeContext) {
   if (!policy) return { failures: ['shared_validator'], status: 'missing' };
   return receiptHelper().checkFeatureReceipt(featureDir, runtimeContext, policy);
 }
+function receiptFixHint(failures, body) {
+  const helper = receiptHelper();
+  return typeof helper.receiptFixHint === 'function' ? helper.receiptFixHint(failures, body) : null;
+}
 function readTaskProof(featureDir, taskPath) {
   return receiptHelper().readTaskProof(featureDir, taskPath, getSharedPolicy() || {});
 }
@@ -115,6 +119,7 @@ module.exports = {
   loadSharedPolicy,
   loadSharedReceipt,
   readTaskProof,
+  receiptFixHint,
   safeTaskFile,
   validateCanonicalReceipt,
 };

package/src/codex/hooks/lib/spec-utils.cjs

@@ -152,17 +152,10 @@ function readActiveFeatureTarget(options) {
   return resolver.readActiveFeatureTarget(options);
 }
 
-function resolvePersistedSpec(options) {
-  const resolver = sharedResolver();
-  if (typeof resolver.resolvePersistedSpec !== 'function') return null;
-  return resolver.resolvePersistedSpec(options);
-}
-
 module.exports = {
   findActiveSpec,
   extractExplicitTarget,
   readActiveFeatureTarget,
-  resolvePersistedSpec,
   findAllActiveSpecs,
   findAllSpecCandidates,
   resolveActiveSpec,

package/src/codex/hooks/rules.cjs

@@ -79,6 +79,7 @@ try {
   const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');
   const plansPath = resolveProjectPath(projectRoot, runtime.paths?.plans, 'plans');
   const docsPath = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const specsPath = resolveProjectPath(projectRoot, runtime.paths?.specs, 'specs');
   const lines = [];
 
   if ((thinkLang && thinkLang !== respondLang) || respondLang) {
@@ -92,7 +93,7 @@ try {
 
   lines.push(
     '## Rules',
-    `- Markdown: Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
+    `- Markdown: Specs → "${specsPath}/" | Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
     '- Do not create markdown outside those directories unless explicitly asked.',
     `- docs.maxLoc: ${runtime.docs?.maxLoc || 800} lines per doc file`
   );

package/src/codex/hooks/session.cjs

@@ -10,7 +10,6 @@ const {
   readPayload
 } = require('./lib/hook-context.cjs');
 const { clearState } = require('./lib/privacy-state.cjs');
-const { clearState: clearCompletionState } = require('./completion-authority-state.cjs');
 
 function readPackage(projectRoot) {
   try {
@@ -89,7 +88,6 @@ try {
 
   // Approval tokens never survive a session boundary or compaction.
   clearState(projectRoot);
-  clearCompletionState(projectRoot, payload.session_id);
 
   // Orca (onorca.dev) sets ORCA_PANE_KEY in every pane; it is a presence marker, not a
   // secret. ORCA_AGENT_HOOK_TOKEN and ORCA_AGENT_LAUNCH_TOKEN live in the same

package/src/codex/hooks/spec-gate.cjs

@@ -16,9 +16,9 @@ const {
   checkWorkflowReceiptDetails,
   checkWorkflowReceiptSet,
   loadSharedPolicy,
+  receiptFixHint,
 } = require('./lib/spec-receipt.cjs');
 const { taskStatusMap } = require('./lib/spec-utils.cjs');
-const FINAL_STATE = require('./completion-authority-check.cjs');
 
 function emitBlock(reason) {
   process.stdout.write(`${JSON.stringify({ decision: 'block', reason })}\n`);
@@ -53,9 +53,7 @@ try {
   // the payload leaves, which is what made the block unescapable on this runtime too.
   const target = resolver.extractExplicitTarget(payload)
     || resolver.readActiveFeatureTarget({ projectRoot, runtime });
-  let resolved = typeof resolver.resolveWorkflowCandidate === 'function'
-    ? resolver.resolveWorkflowCandidate({ projectRoot, runtime, target, includeCompleted: true })
-    : FINAL_STATE.resolveCandidate({ resolver, projectRoot, runtime, payload });
+  let resolved = resolver.resolveWorkflowCandidate({ projectRoot, runtime, target, includeCompleted: true });
   if (typeof resolver.refineWorkflowGateResolution === 'function') {
     resolved = resolver.refineWorkflowGateResolution(resolved);
   }
@@ -75,7 +73,7 @@ try {
     const lines = [`Completion gate: ${checked.failures.length} done task(s) lack a verification receipt.`];
     for (const failure of checked.failures) {
       lines.push(`- \`${failure.featureName}/${failure.taskPath}\`: failed check(s) ${failure.failures.join(', ')}`);
-      lines.push(`  Write a runtime-bound \`## Receipt\` with the planned command in \`specs/${failure.featureName}/${failure.taskPath}\`.`);
+      lines.push(`  In \`specs/${failure.featureName}/${failure.taskPath}\`: ${receiptFixHint(failure.failures, failure.body) || 'write a runtime-bound `## Receipt` with the planned command'}.`);
     }
     emitBlock(lines.slice(0, 8).join('\n'));
     process.exit(0);
@@ -108,18 +106,10 @@ try {
   const lifecyclePhase = activeSpec.current_phase || activeSpec.phase;
   const explicitCloseout = ['done', 'completed', 'complete'].includes(activeSpec.status)
     || ['closeout', 'completion', 'completed', 'complete'].includes(lifecyclePhase);
-  if (!processWorkflow && activeSpec.schema_version === '2.1') {
-    const finalState = FINAL_STATE.evaluateCloseout({
-      policy: POLICY,
-      projectRoot,
-      runtime,
-      payload: { ...payload, session_id: sessionIdentity(payload) },
-    });
-    if (!finalState.ok) {
-      emitBlock(`Completion gate: ${finalState.reason}`);
-      process.exit(0);
-    }
-    if (finalState.active) process.exit(0);
+  // Legacy 2.1 closeout is retired; a 2.1 packet mid-execution keeps the ordinary receipt checks.
+  if (!processWorkflow && activeSpec.schema_version === '2.1' && explicitCloseout) {
+    emitBlock('Completion gate: Legacy spec.json closeout is no longer supported; move the packet to plan.md with flat task files');
+    process.exit(0);
   }
   const runtimeContext = POLICY.deriveRuntimeContext({
     projectRoot,
@@ -228,7 +218,7 @@ try {
     lines.push(result.taskPath === 'feature-receipt.md'
       ? `  Run final integration proof, then write \`specs/${active.featureName}/feature-receipt.md\`.`
       : processWorkflow
-        ? `  Write a runtime-bound \`## Receipt\` with command output in \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`.`
+        ? `  In \`specs/${active.featureName}/${path.posix.basename(result.taskPath)}\`: ${receiptFixHint(result.failures, result.body) || 'write a runtime-bound `## Receipt` with command output'}.`
         : `  Write canonical proof to \`specs/${active.featureName}/receipts/${path.posix.basename(result.taskPath)}\`; legacy \`## Evidence\` remains read-compatible.`);
   }
   if (completionBlocked) {