@haposoft/cafekit 0.16.0-rc.8 → 0.16.1

package/src/claude/skills/test/references/failure-triage.md

@@ -1,128 +1,62 @@
-# Failure Triage
+# Failure triage
 
-Classify every test failure into a category, then apply the matching action.
-Referenced by `SKILL.md` Phase 3 and by the `test-runner` agent.
+Classify observed failures, preserve real output, and return the cause to the
+implementation owner. Testing never edits implementation or tests.
 
----
+## Categories
 
-## Failure Categories
-
-| # | Category | Description | Source |
-|---|---|---|---|
-| 1 | **Compile Error** | Syntax, type, or import errors preventing test execution | Pre-flight (tsc, eslint, flake8...) |
-| 2 | **Logic Error** | Test ran but assertion failed — expected vs actual mismatch | Unit / Integration test output |
-| 3 | **Environment Error** | Missing env vars, DB not running, port conflict, network unreachable | Integration / E2E test output |
-| 4 | **Flaky Test** | Pass/fail intermittently — indicates race condition or shared state | Observed across multiple runs |
-| 5 | **Coverage Gap** | Tests pass but coverage drops below threshold | Coverage report |
-| 6 | **Build Error** | Code compiles but production build fails | Build step output |
-| 7 | **UI Console Error** | JavaScript errors or pageerrors captured during browser session | `console.js` output |
-| 8 | **UI Network Error** | API responses with 4xx or 5xx status during page load | `network.js` output |
-| 9 | **UI Performance** | Core Web Vitals exceed acceptable thresholds, or memory leak | `performance.js` |
-| 10 | **Accessibility Error** | Interactive elements missing accessible names or labels | `aria-snapshot.js` |
-| 11 | **User Flow Error** | E2E form submission failed, unexpected redirect | `click.js` + `fill.js` |
-| 12 | **SEO Error** | Missing meta tags, H1 issues, broken canonical | `evaluate.js` |
-| 13 | **Security Warning** | Missing HTTP security headers, exposed secrets | `network.js` / source |
-| 14 | **Broken Links** | Internal crawler found 404s on discovered pages | Phase 0.5 Crawler |
-| 15 | **UI Visual Error** | AI visual analysis detected layout break, overlap | `gemini_batch_process.py` |
-
----
-
-## Triage Decision Tree
-
-```
-Failure detected
-│
-├─ Compile Error (#1)
-│   → STOP immediately. Do NOT run further tests.
-│   → Report: file, line, error message.
-│   → Action: return to implementer. Fix compile errors first.
-│
-├─ Logic Error (#2)
-│   → Report: test name, file:line, expected value, actual value.
-│   → Action: return to implementer with precise location.
-│   → Do NOT modify test to make it pass.
-│
-├─ Environment Error (#3)
-│   → Report: which service/env var is missing.
-│   → Action: escalate to USER (not implementer).
-│     "Environment issue: [DB/service] not reachable. Please start it."
-│
-├─ Flaky Test (#4)
-│   → Report: test name + "intermittent failure observed".
-│   → Action: flag for implementer review.
-│     Likely cause: shared state, async timing, or test ordering.
-│
-├─ Coverage Gap (#5)
-│   → Report: specific uncovered files and functions (not just %).
-│   → Action: flag as PARTIAL verdict. Do not block PASS.
-│     "Coverage gap in: src/auth/refresh.ts — add tests for error path"
-│
-├─ Build Error (#6)
-│   → Report: build command, error output (last 20 lines).
-│   → Action: return to implementer.
-│
-├─ UI Console Error (#7)
-│   → Report: error message, source file, line number.
-│   → Action: return to implementer if JS error.
-│     If external script error: flag as warning only.
-│
-├─ UI Network Error (#8)
-│   → Report: endpoint URL, status code, response body excerpt.
-│   → Action: 404 → implementer (missing route/resource).
-│     500 → implementer (server error). 401/403 → auth issue (user).
-│
-├─ UI Performance (#9)
-│   → Report: specific metric name + actual value + threshold.
-│   → Action: flag as warning. Block PASS only if LCP > 4s or CLS > 0.25.
-│
-├─ Accessibility Error (#10)
-│   → Report: element role + missing attribute.
-│   → Action: return to implementer. Add aria-label / alt / for attributes.
-│
-├─ User Flow Error (#11)
-│   → Report: step failed (e.g., login submit), expected vs actual URL/state.
-│   → Action: return to implementer to fix E2E UI flow.
-│
-├─ SEO Error (#12)
-│   → Report: missing tag or invalid setup (e.g., no H1, bad canonical).
-│   → Action: return to implementer. Add missing HTML meta tags.
-│
-├─ Security Warning (#13)
-│   → Report: missing header names or exposed secret pattern.
-│   → Action: return to implementer. Add helmet/headers or remove secrets.
-│
-├─ Broken Links (#14)
-│   → Report: crawler source URL → broken target URL (404).
-│   → Action: return to implementer to fix href paths.
-│
-└─ UI Visual Error (#15)
-    → Report: AI parsed visual issue (e.g., button overlapping text).
-    → Action: return to implementer to fix CSS/layout issues.
-```
-
----
-
-## Escalation Protocol
-
-| Failure count | Verdict | Action |
+| Category | Evidence | Default result |
 |---|---|---|
-| 0 failures | **PASS** | Proceed to hapo:code-review |
-| 1–2 failures | **FAIL** | Return to implementer with targeted fix list |
-| 3–10 failures | **FAIL** | Return to implementer, flag as "significant failures" |
-| > 10 failures OR 0 tests pass | **COLLAPSE** | Call `AskUserQuestion`: "Test suite critically broken. User intervention required." |
-| Only coverage gaps | **PARTIAL** | Proceed to hapo:code-review, attach coverage gap list |
-| Environment errors only | **BLOCKED** | Escalate to user (not implementer) |
-
----
-
-## Report Format per Failure
+| Compilation or packaging | command, exit, relevant file/line | `FAIL` |
+| Logic/contract | named probe, expected, observed | `FAIL` |
+| Environment/prerequisite | missing tool, service, variable, permission | `BLOCKED` before execution; otherwise `FAIL` after an attempted command |
+| Flaky/nondeterministic | repeated current runs with differing outcomes | `FAIL` |
+| Coverage/reachability gap | exact uncovered branch or unreachable surface | `FAIL`, or `PASS_WITH_WARNINGS` only when explicitly non-required |
+| UI console/network/flow | URL path, safe status, redacted error | `FAIL` when required |
+| Accessibility/visual/performance/SEO | metric or element plus declared threshold | requirement decides `FAIL` or `PASS_WITH_WARNINGS` |
+| Security/auth safety | unsafe origin, redirect, action, or disclosure risk | `BLOCKED` before execution; otherwise `FAIL` |
+| Proof integrity | malformed, duplicate, stale, skipped, contradictory, zero-test, or unknown proof | `BLOCKED` |
+
+## Canonical verdicts
+
+Use only `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`.
+
+- `PASS`: every required branch executed and passed under the exact current
+  command/provenance with no skips or warnings.
+- `PASS_WITH_WARNINGS`: required proof passed, but a real non-required warning
+  remains. It does not close a process-first task.
+- `FAIL`: execution was attempted and a required assertion, command,
+  reachability check, artifact, redaction check, or safety expectation failed.
+- `BLOCKED`: safe execution could not begin or proof structure/identity cannot
+  be trusted. State the changed prerequisite; do not blind-retry.
+
+Do not emit `PARTIAL`, `COLLAPSE`, `NO_TESTS`, or an unknown result. Normalize
+those legacy diagnostics to one of the four verdicts and keep work unfinished.
+Failure count never changes the lattice: aggregation remains
+`FAIL` > `BLOCKED` > `PASS_WITH_WARNINGS` > `PASS`.
+
+## Triage sequence
+
+1. Record the exact redacted command, exit, counts, named probe, expected, and
+   observed result.
+2. Separate product failure from environment blocker and proof-integrity error.
+3. Preserve the shortest useful output excerpt and relevant path/line.
+4. Do not change assertions, install tools, clean project drift, retry without a
+   stated hypothesis, or reuse remembered output.
+5. Return the canonical verdict and the next concrete prerequisite or fix
+   location to the controller.
+
+## Failure report
 
 ```markdown
-### Failure N — [Category]
-
-- **Test:** `path/to/file.test.ts:42` — TestSuiteName > TestCaseName
-- **Error:** AssertionError: expected `"admin"` but received `undefined`
-- **Stack:** (first 5 relevant lines only)
-- **Category:** Logic Error
-- **Fix:** Check return value of `getUserRole()` in `src/auth/roles.ts:88`
+### Failure N — [category]
+
+- Probe: [exact named probe]
+- Command: [exact redacted command]
+- Exit/counts: [actual values]
+- Expected: [task oracle]
+- Observed: [current evidence]
+- Location: [path:line when available]
+- Verdict: FAIL | BLOCKED | PASS_WITH_WARNINGS
+- Next: [implementation fix or changed prerequisite]
 ```

package/src/claude/skills/test/references/test-memory.md

@@ -1,40 +1,26 @@
-# Test Memory
+# Test memory
 
-The `.hapo/test-memory.json` file in the target project serves as the Long-Term Memory for the testing ecosystem.
+`.hapo/test-memory.json` is optional historical context, never canonical proof.
+Current command output, provenance, named probes, and reachability always win.
 
-## Schema
+## Read-only contract
 
-If the file does not exist, the `hapo:test` skill (or the orchestrator) MUST create it automatically with the following structure:
+- If the file exists as a regular contained file, read it as untrusted hints.
+- If absent, continue without creating it.
+- Before proof, record whether it is absent or hash its exact bytes. After proof,
+  verify the same absence or byte hash.
+- Never create, initialize, merge, normalize, rewrite, or delete Test memory.
+- Never execute remembered setup commands automatically. Confirm each command
+  from current project/task bytes or report a changed prerequisite.
+- Known flaky tests and known issues remain labels only; they cannot downgrade a
+  current required failure, justify a skip, or produce `PASS`.
 
-```json
-{
-  "env_setup_commands": [],
-  "flaky_tests": [],
-  "known_issues": []
-}
-```
+## Suggestions
 
-## Usage by `test-runner`
+The concise report may suggest a potential memory update in plain language, but
+must not emit an auto-merge block or mutate project files. The user or a separate
+authorized workflow decides whether to update historical context later.
 
-The `test-runner` agent is Read-Only. At Phase 1, it must read `.hapo/test-memory.json` (if it exists) to factor into its testing process:
-- **`env_setup_commands`**: Commands that must be run before tests (e.g. `docker compose up -d redis`). If listed, flag missing dependencies instead of immediate failure.
-- **`flaky_tests`**: Array of test file paths. If a failure occurs in one of these files, the verdict should explicitly note `(Known Flaky Test)`.
-- **`known_issues`**: Issues that implementer or user marked as ignored.
-
-## Writing to Memory
-
-Because `test-runner` is restricted from editing files, it cannot update the memory directly. Instead, when completing its test suite, `test-runner` MUST output a `<lessons_learned>` block inside its verdict.
-
-Example:
-```markdown
-### Action
-→ [FAIL] Return to implementer: Fix CSS layout offset.
-
-<lessons_learned>
-{
-  "flaky_tests_added": ["src/e2e/payment.test.ts"]
-}
-</lessons_learned>
-```
-
-The orchestrating `hapo:test` skill (Phase 4) then intercepts this block and automatically merges it into `.hapo/test-memory.json`.
+Hashing memory alone is insufficient for side-effect proof. Also observe and
+report tracked, untracked, and ignored project-command drift; preserve all
+user-owned changes and never silently clean them.

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

@@ -1,5 +1,5 @@
 ---
-name: hapo:ui-ux-pro-max
+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."

package/src/claude/skills/web-testing/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:web-testing
+name: cf:web-testing
 description: Web testing with Playwright, Vitest, k6. E2E/unit/integration/load/security/visual/a11y testing. Use for test automation, flakiness, Core Web Vitals, mobile gestures, cross-browser.
 license: Apache-2.0
 user-invocable: true

package/src/claude/skills/xlsx/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hapo:xlsx
+name: cf:xlsx
 description: Create, edit, analyze spreadsheets (.xlsx, .csv, .tsv). Use for Excel formulas, data analysis, visualization, formatting, pivot tables, charts, formula recalculation.
 license: Proprietary. LICENSE.txt has complete terms
 user-invocable: true

package/src/claude/status.cjs

@@ -26,6 +26,10 @@ 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 ~
  */
@@ -111,6 +115,21 @@ function buildUsageString(ctx) {
  * Combines parts based on content length vs terminal width
  * Tries to minimize lines while keeping content readable
  */
+function buildBranchPart(ctx) {
+  if (!ctx.gitBranch) return '';
+  let branchPart = `🌿 ${ctx.gitBranch}`;
+  // Build git status indicators: (unstaged, +staged, ahead↑, behind↓)
+  const gitIndicators = [];
+  if (ctx.gitUnstaged > 0) gitIndicators.push(`${ctx.gitUnstaged}`);
+  if (ctx.gitStaged > 0) gitIndicators.push(`+${ctx.gitStaged}`);
+  if (ctx.gitAhead > 0) gitIndicators.push(`${ctx.gitAhead}↑`);
+  if (ctx.gitBehind > 0) gitIndicators.push(`${ctx.gitBehind}↓`);
+  if (gitIndicators.length > 0) {
+    branchPart += ` ${yellow(`(${gitIndicators.join(', ')})`)}`;
+  }
+  return branchPart;
+}
+
 function renderSessionLines(ctx) {
   const lines = [];
   const termWidth = getTerminalWidth();
@@ -118,20 +137,7 @@ function renderSessionLines(ctx) {
 
   // Build all atomic parts for flexible composition (no colors on static text)
   const dirPart = `📁 ${ctx.currentDir}`;
-
-  let branchPart = '';
-  if (ctx.gitBranch) {
-    branchPart = `🌿 ${ctx.gitBranch}`;
-    // Build git status indicators: (unstaged, +staged, ahead↑, behind↓)
-    const gitIndicators = [];
-    if (ctx.gitUnstaged > 0) gitIndicators.push(`${ctx.gitUnstaged}`);
-    if (ctx.gitStaged > 0) gitIndicators.push(`+${ctx.gitStaged}`);
-    if (ctx.gitAhead > 0) gitIndicators.push(`${ctx.gitAhead}↑`);
-    if (ctx.gitBehind > 0) gitIndicators.push(`${ctx.gitBehind}↓`);
-    if (gitIndicators.length > 0) {
-      branchPart += ` ${yellow(`(${gitIndicators.join(', ')})`)}`;
-    }
-  }
+  const branchPart = buildBranchPart(ctx);
 
   // Active plan indicator (disabled for now - code preserved)
   // const planPart = ctx.activePlan ? `📋 ${ctx.activePlan}` : '';
@@ -150,6 +156,7 @@ function renderSessionLines(ctx) {
   const usageStr = buildUsageString(ctx);
   if (usageStr) {
     sessionPart += `  ⌛ ${usageStr.replace(/\)$/, ' used)')}`;
+    if (ctx.weeklyText) sessionPart += `  ${ctx.weeklyText}`;
   }
 
   // Build stats part (only lines changed now)
@@ -313,7 +320,7 @@ function renderMinimal(ctx) {
     parts.push(`${batteryIcon} ${ctx.contextPercent}%`);
   }
   const usageStr = buildUsageString(ctx);
-  if (usageStr) parts.push(`⏰ ${usageStr}`);
+  if (usageStr) parts.push(`⏰ ${usageStr}${ctx.weeklyText ? `  ${ctx.weeklyText}` : ''}`);
   if (ctx.gitBranch) parts.push(`🌿 ${ctx.gitBranch}`);
   parts.push(`📁 ${ctx.currentDir}`);
   console.log(parts.join('  '));
@@ -329,7 +336,7 @@ function renderCompact(ctx) {
     line1 += `  ${coloredBar(ctx.contextPercent, 12)} ${ctx.contextPercent}%`;
   }
   const usageStr = buildUsageString(ctx);
-  if (usageStr) line1 += `  ⌛ ${usageStr}`;
+  if (usageStr) line1 += `  ⌛ ${usageStr}${ctx.weeklyText ? `  ${ctx.weeklyText}` : ''}`;
   console.log(line1.replace(/ /g, '\u00A0'));
 
   // Line 2: Location (branch + directory)
@@ -359,13 +366,84 @@ function render(ctx, singleLineMode = false) {
     if (todosLine) lines.push(todosLine);
   }
 
-  // Output all lines with non-breaking spaces for alignment
+  writeStyledLines(lines);
+}
+
+/**
+ * Output lines with non-breaking spaces for alignment
+ */
+function writeStyledLines(lines) {
   for (const line of lines) {
     const outputLine = colors.shouldUseColor ? `${RESET}${line.replace(/ /g, '\u00A0')}` : line;
     console.log(outputLine);
   }
 }
 
+// ============================================================================
+// CONFIGURABLE LAYOUT
+// Global shape: { lines: [[sectionId, ...], ...] } — each inner array is one
+// output line; modes only slice the line count (minimal = 1, compact = 2,
+// full = all). Agents/todos stay outside `lines` behind their own flags.
+// ============================================================================
+
+const LAYOUT_SECTION_IDS = ['model', 'context', 'quota', 'directory', 'git', 'plan', 'cost', 'changes'];
+
+const LAYOUT_SECTIONS = {
+  model: (ctx) => `🤖 ${ctx.modelName}`,
+  context: (ctx) => ctx.contextPercent > 0
+    ? `${coloredBar(ctx.contextPercent, 12)} ${ctx.contextPercent}%`
+    : null,
+  quota: (ctx) => {
+    const usageStr = buildUsageString(ctx);
+    if (!usageStr) return null;
+    let out = `\u231B ${usageStr.replace(/\)$/, ' used)')}`;
+    if (ctx.weeklyText) out += `  ${ctx.weeklyText}`;
+    return out;
+  },
+  directory: (ctx) => `📁 ${ctx.currentDir}`,
+  git: (ctx) => buildBranchPart(ctx) || null,
+  plan: (ctx) => ctx.activePlan ? `📋 ${ctx.activePlan}` : null,
+  cost: (ctx) => ctx.costText ? `💵 ${ctx.costText.replace(/(\.\d{2})\d+/, '$1')}` : null,
+  changes: (ctx) => (ctx.linesAdded > 0 || ctx.linesRemoved > 0)
+    ? `📝 ${green(`+${ctx.linesAdded}`)} ${red(`-${ctx.linesRemoved}`)}`
+    : null,
+};
+
+/**
+ * Normalize a raw statuslineLayout config value.
+ * Unknown section ids are ignored; an empty or invalid layout returns null so
+ * rendering falls back to the default renderers.
+ */
+function normalizeStatuslineLayout(raw) {
+  if (!raw || typeof raw !== 'object' || !Array.isArray(raw.lines)) return null;
+  const lines = raw.lines
+    .filter((line) => Array.isArray(line))
+    .map((line) => line.filter((id) => LAYOUT_SECTION_IDS.includes(id)))
+    .filter((line) => line.length > 0);
+  if (lines.length === 0) return null;
+  return { lines, agents: raw.agents !== false, todos: raw.todos !== false };
+}
+
+/**
+ * Render with a user-configured layout. Modes only slice the line count.
+ */
+function renderLayout(ctx, layout, mode) {
+  const lineLimit = mode === 'minimal' ? 1 : mode === 'compact' ? 2 : layout.lines.length;
+  const lines = [];
+  for (const ids of layout.lines.slice(0, lineLimit)) {
+    const parts = ids.map((id) => LAYOUT_SECTIONS[id](ctx)).filter(Boolean);
+    if (parts.length > 0) lines.push(parts.join('  '));
+  }
+  if (mode !== 'minimal' && mode !== 'compact') {
+    if (layout.agents) lines.push(...renderAgentsLines(ctx.transcript));
+    if (layout.todos) {
+      const todosLine = renderTodosLine(ctx.transcript);
+      if (todosLine) lines.push(todosLine);
+    }
+  }
+  writeStyledLines(lines);
+}
+
 // ============================================================================
 // MAIN
 // ============================================================================
@@ -446,6 +524,7 @@ async function main() {
 
     // Session timer - read actual reset time from usage limits cache
     let sessionText = '';
+    let weeklyText = '';
     const transcriptPath = data.transcript_path;
 
     // Parse transcript for tools/agents/todos
@@ -459,9 +538,11 @@ async function main() {
         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 {
+        } else if (cache.status === 'available' && fresh) {
           const fiveHour = cache.data?.five_hour;
           usagePercent = fiveHour?.utilization ?? null;
           const resetAt = fiveHour?.resets_at;
@@ -474,6 +555,19 @@ async function main() {
               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)`;
+              }
+            }
+          }
         }
       }
     } catch {}
@@ -502,6 +596,7 @@ async function main() {
       activePlan,
       contextPercent,
       sessionText,
+      weeklyText,
       usagePercent,
       costText,
       linesAdded,
@@ -515,21 +610,28 @@ async function main() {
     const statuslineMode = config.statusline || 'full';
     colors.setColorEnabled(config.statuslineColors !== false);
 
-    // Render based on mode
-    switch (statuslineMode) {
-      case 'none':
-        console.log('');
-        break;
-      case 'minimal':
-        renderMinimal(ctx);
-        break;
-      case 'compact':
-        renderCompact(ctx);
-        break;
-      case 'full':
-      default:
-        render(ctx, false);
-        break;
+    // Render based on mode. A valid statuslineLayout takes over line
+    // composition; an absent, empty, or invalid layout falls back to the
+    // default renderers below.
+    const layout = normalizeStatuslineLayout(config.statuslineLayout);
+    if (statuslineMode !== 'none' && layout) {
+      renderLayout(ctx, layout, statuslineMode);
+    } else {
+      switch (statuslineMode) {
+        case 'none':
+          console.log('');
+          break;
+        case 'minimal':
+          renderMinimal(ctx);
+          break;
+        case 'compact':
+          renderCompact(ctx);
+          break;
+        case 'full':
+        default:
+          render(ctx, false);
+          break;
+      }
     }
 
   } catch (err) {

package/src/codex/AGENTS.md

@@ -1,20 +1,30 @@
 ## Codex runtime
 
 - Repository instructions live in `AGENTS.md`.
-- CafeKit skills live in `.agents/skills/`; invoke them as `$hapo-<name>` or browse with `/skills`. Edit skills in the project, not in a global skills directory.
+- CafeKit skills live in `.agents/skills/`; invoke them as `$cf-<name>` or browse with `/skills`. Edit skills in the project, not in a global skills directory.
 - Run Python skill scripts with the project venv:
   - macOS/Linux: `.agents/skills/.venv/bin/python3 scripts/<script>.py`
   - Windows: `.agents\\skills\\.venv\\Scripts\\python.exe scripts\\<script>.py`
 - CafeKit agents live in `.codex/agents/*.toml` and are auto-discovered after the repository is trusted.
 - Runtime support lives in `.codex/rules/`, `.codex/scripts/`, `.codex/references/`, and `.codex/runtime.json`.
+- 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.
+- 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.
 - Project hooks live in `.codex/hooks.json`; review trusted hooks with `/hooks`.
-- New Specs work uses the process-first flow. `$hapo-specs` opens C1, writes
+- New Specs work uses the process-first flow. `$cf-specs` opens C1, writes
   `specs/<feature>/plan.md` with flat `task-NN-*.md` files beside it, then opens
   C2 after adversarial review. It never starts implementation.
-- Start implementation only through a new explicit `$hapo-develop` invocation.
+- 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.
-- Use `$hapo-sync` for surgical updates to observed file state. A done task
+- Use `$cf-sync` for surgical updates to observed file state. A done task
   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.

package/src/codex/hooks/docs-sync.cjs

@@ -11,11 +11,14 @@ const {
   resolveProjectPath
 } = require('./lib/hook-context.cjs');
 
-function latestSourceHash(projectRoot, docsRelative) {
+function latestSourceHash(projectRoot, excludedRelatives) {
   try {
     return execFileSync(
       'git',
-      ['log', '-1', '--format=%H', '--', '.', `:(exclude)${docsRelative}`],
+      [
+        'log', '-1', '--format=%H', '--', '.',
+        ...excludedRelatives.map((relative) => `:(exclude,literal)${relative}`)
+      ],
       {
         cwd: projectRoot,
         encoding: 'utf8',
@@ -32,7 +35,9 @@ try {
   if (!payload) process.exit(0);
   const { projectRoot, runtime } = getHookContext(payload);
   const docsDir = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const specsDir = resolveProjectPath(projectRoot, runtime.paths?.specs, 'specs');
   const docsRelative = path.relative(projectRoot, docsDir).replace(/\\/g, '/');
+  const specsRelative = path.relative(projectRoot, specsDir).replace(/\\/g, '/');
   const hasCode = [
     'src', 'app', 'lib', 'package.json', 'index.js', 'main.py'
   ].some((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
@@ -46,7 +51,7 @@ try {
       '> Create baseline architecture and project-overview docs, then record the source Git hash in `docs/.sync_hash`.'
     );
   } else {
-    const currentHash = latestSourceHash(projectRoot, docsRelative);
+    const currentHash = latestSourceHash(projectRoot, [docsRelative, specsRelative]);
     const trackingFile = path.join(docsDir, '.sync_hash');
     const previousHash = fs.existsSync(trackingFile)
       ? fs.readFileSync(trackingFile, 'utf8').trim()

package/src/codex/hooks/lib/hook-context.cjs

@@ -113,12 +113,25 @@ function atomicWrite(file, content, mode = 0o600) {
   fs.renameSync(temp, file);
 }
 
+/**
+ * Where a hook keeps its own generated state: crash logs, session reservations
+ * and the gate/tollgate caches.
+ *
+ * Installed, that is `<project>/.codex/hooks/.logs/`. Under this package's own
+ * tests PROJECT_ROOT resolves to `packages/spec/src`, so the same write lands in
+ * the source tree; it accumulated silently there because the repository ignores
+ * `.codex` at any depth. Source-tree runs therefore write to a temp directory.
+ */
+function hookStateDir(projectRoot) {
+  const root = projectRoot || PROJECT_ROOT;
+  return String(root).includes(`${path.sep}packages${path.sep}spec${path.sep}src`)
+    ? path.join(require('os').tmpdir(), 'cafekit-hook-logs', 'codex')
+    : path.join(root, '.codex', 'hooks', '.logs');
+}
+
 function logCrash(hook, error) {
   try {
-    const isSourceTree = PROJECT_ROOT.includes(`${path.sep}packages${path.sep}spec${path.sep}src`);
-    const dir = isSourceTree
-      ? path.join(require('os').tmpdir(), 'cafekit-hook-logs', 'codex', hook)
-      : path.join(PROJECT_ROOT, '.codex', 'hooks', '.logs');
+    const dir = hookStateDir(PROJECT_ROOT);
     fs.mkdirSync(dir, { recursive: true });
     fs.appendFileSync(
       path.join(dir, 'hook-log.jsonl'),
@@ -138,6 +151,7 @@ module.exports = {
   PROJECT_ROOT,
   atomicWrite,
   getHookContext,
+  hookStateDir,
   logCrash,
   readPayload,
   readRuntime,