@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

package/README.md

@@ -138,21 +138,97 @@ cat .claude/cafekit.json
 cat .codex/cafekit.json
 ```
 
+### Statusline configuration
+
+The Claude statusline reads three keys from `.claude/runtime.json`:
+
+- `"statusline"`: render mode — `full` (default), `compact`, `minimal`, or `none`.
+- `statuslineColors`: set `false` to disable ANSI colors (`NO_COLOR` also wins).
+- `statuslineLayout`: optional custom layout. Global shape
+  `{ "lines": [["model", "context"], ["directory", "git"]] }` — each inner
+  array is one output line; modes only slice the line count (minimal = first
+  line, compact = first two, full = all). Valid section ids: `model`,
+  `context`, `quota`, `directory`, `git`, `plan`, `cost`, `changes`. Unknown
+  ids are ignored; an empty or invalid layout falls back to the default
+  renderers, and leaving the key out keeps the default output unchanged. The
+  `cost` section renders only when enabled here, billing mode is API, and cost
+  data exists. Quota shows five-hour and weekly windows only while the usage
+  cache is fresh.
+
 ## Core Skills
 
 CafeKit ships many skills, but the main release surface is:
 
-- `/hapo:question <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when local evidence is insufficient
-- `/hapo:brainstorm <idea-or-problem>`: scout the repo, clarify exact requirements, compare approaches, and hand off to specs
-- `/hapo:specs <feature-description>`: create or resume a structured spec workflow
-- `/hapo:develop <feature-name>`: implement from approved spec artifacts
-- `/hapo:debug <issue>`: diagnose bugs, incidents, CI failures, flaky tests, UI regressions, and performance issues before fixing
-- `/hapo:hotfix <issue>`: fix diagnosed bugs with root-cause, verification, prevention, and side-effect gates
-- `/hapo:docs [--init|--update|--summarize|--reconstruct]`: create project docs or reconstruct as-is system documentation from source code
-- `/hapo:test [scope|--full]`: run verification and return a structured verdict
-- `/hapo:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
+- `/cf:ask <question> [--repo|--web|--both|--brief|--deep]`: answer questions using repo evidence first, then external/current sources when local evidence is insufficient
+- `/cf:scout <search-target>`: discover relevant files locally first, delegating only for permitted broad independent scopes
+- `/cf:brainstorm <idea-or-problem>`: scout the repo, clarify exact requirements, compare approaches, and hand off to specs
+- `/cf:research <decision>`: choose proportional depth and return traceable evidence for an uncertain technical decision
+- `/cf:route <material-request>`: classify ambiguous, multi-step, multi-domain, or elevated-risk work and compose the shortest valid installed chain
+- `/cf:loop <bounded-experiment>`: run explicit-only numeric optimization in an isolated worktree and return a base-bound patch handoff
+- `/cf:specs <feature-description>`: create or resume a structured spec workflow
+- `/cf:develop <feature-name>`: implement from approved spec artifacts
+- `/cf:debug <issue>`: run adaptive-depth, diagnostic-only root-cause analysis with elimination and prevention-aware handoff
+- `/cf:fix <issue>`: repair the diagnosed root cause with proportional depth; Quick/local stays direct, while Standard and Incident/deep bound the repair and use post-diagnosis research, brainstorm, or staged planning only when evidence leaves a real decision; every path consumes the `cf:debug` handoff and reports shared `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED` verdicts through verification, prevention, and side-effect gates
+- `/cf:test [scope|--full]`: run verification and return a structured verdict
+- `/cf:code-review [scope|--pending]`: adversarial review focused on correctness, regressions, and security
+
+### Adaptive Brainstorm controls
+
+Brainstorm stays proportional by default: Direct classification runs before any
+analysis overlay, then non-direct work selects the smallest adequate Standard or
+Deep depth. Controls are parsed only from the leading control segment. Combine
+the single-use exact flags `--deep`, `--visual`, and `--advice` in any order;
+an unknown or duplicate leading `--*` stops with usage and no action. `--` ends
+controls, so literal flag content can start with `/cf:brainstorm -- --dry-run`.
+
+`--deep` raises non-direct analysis depth only. `--visual` changes presentation
+and falls back to text. `--advice` uses the advisory brainstormer only after a
+material choice exists. External visual/adviser context is minimized and
+redacted first; neither overlay writes, approves, persists, dispatches, or
+completes work. Chat is the default output. A durable file needs explicit user
+authority, and no Brainstorm output is live proof or Specs/Develop approval or
+execution authority.
+
+### Adaptive Research and bounded Loop
+
+Use `/cf:research` when the result is a decision: Quick, Standard, or Deep
+research binds material claims to a URL or repository anchor, authority,
+date/version, applicability, and `confirmed`, `inferred`, or `unresolved`
+state. Research returns evidence and tradeoffs; it does not implement the
+recommendation or guarantee correctness.
+
+Use `/cf:loop` only by explicit request and only after its preflight freezes
+Goal, isolated Scope, finite numeric Metric and Direction, reproducible
+Baseline, distinct Guard, noise policy and minimum delta, budget, and stop
+conditions. Each iteration stays in a detached worktree. The result is a
+base-bound isolated patch handoff, never an automatic apply, commit, push, or
+guarantee of improvement.
+
+```text
+/cf:research Compare current local-first search libraries for this repository
+/cf:loop Goal="reduce parser latency" Scope="packages/parser" Metric="median ms, lower" Baseline="pinned base" Guard="npm test" Noise="MAD; minimum delta 2%" Budget="10 iterations" Stop="budget, drift, or failed guard"
+$cf-research Compare current local-first search libraries for this repository
+$cf-loop Goal="reduce parser latency" Scope="packages/parser" Metric="median ms, lower" Baseline="pinned base" Guard="npm test" Noise="MAD; minimum delta 2%" Budget="10 iterations" Stop="budget, drift, or failed guard"
+```
+
+Optional document skills are `docs`, `docx`, `pdf`, `pptx`, `xlsx`, and
+`ai-multimodal`. Select them interactively or run:
 
-Common companion skills bundled in this package include `inspect`, `research`, `ai-multimodal`, `frontend-development`, `backend-development`, and `react-best-practices`.
+```bash
+npx @haposoft/cafekit --with-document-skills
+```
+
+Fresh non-interactive installs leave them out by default. Use
+`--without-document-skills` to skip them or remove pristine CafeKit-owned
+copies; user-modified files are preserved. Documentation validators, hooks,
+and the `docs-keeper` agent remain part of the core runtime.
+
+When installed, `cf:docs` consumes a post-task docs checkpoint from
+Develop/Sync (`none | minor | major` — `none` reports only, `minor`/`major`
+update only affected existing docs, and a checkpoint never invents a new
+document), dispatches `docs-keeper` or parallel readers only through the
+Delegation Gate, and keeps every reconstructed claim on the
+`Observed | Inferred | Unknown` evidence taxonomy.
 
 CafeKit uses rule-based skill routing guidance instead of an automatic prompt-scoring hook. See `.claude/rules/skill-workflow-routing.md`, `.claude/rules/skill-domain-routing.md`, or run:
 
@@ -160,7 +236,16 @@ CafeKit uses rule-based skill routing guidance instead of an automatic prompt-sc
 node .claude/scripts/generate-skill-catalog.cjs --skills
 ```
 
-On Codex, invoke the transformed native skill names as `$hapo-<name>` or browse
+Routing uses progressive disclosure: live catalog metadata selects a candidate,
+the selected `SKILL.md` supplies its contract, and only relevant references are
+loaded. Invoke an installed skill directly for explicit or obvious low-risk
+work; use `cf:route` only when classification or chaining is material. When a
+capability or agent is absent, continue inline when safe or name the gap.
+Hooks are not a skill router and never grant capability presence or authority. Source
+and installed projections are verified; live-model adherence remains
+`UNPROVEN`, not deterministic.
+
+On Codex, invoke the transformed native skill names as `$cf-<name>` or browse
 them with `/skills`. Explicit custom-agent delegation uses snake_case agent
 names and `fork_turns: "none"`.
 
@@ -169,32 +254,36 @@ names and `fork_turns: "none"`.
 Claude Code:
 
 ```bash
-/hapo:question "Which files define the current CafeKit install/runtime behavior?" --repo
-/hapo:brainstorm Explore approaches for a Google Meet transcript extension
-/hapo:specs Build a Google Meet transcript extension with AI summaries
-/hapo:develop meet-transcript-mvp
-/hapo:test meet-transcript-mvp --full
-/hapo:code-review meet-transcript-mvp --pending
+/cf:ask "Which files define the current CafeKit install/runtime behavior?" --repo
+/cf:scout "Find the runtime entrypoints for skill installation"
+/cf:brainstorm Explore approaches for a Google Meet transcript extension
+/cf:research Compare current transcript storage options for this repository
+/cf:specs Build a Google Meet transcript extension with AI summaries
+/cf:develop meet-transcript-mvp
+/cf:test meet-transcript-mvp --full
+/cf:code-review meet-transcript-mvp --pending
 ```
 
 Codex CLI:
 
 ```text
-$hapo-question "Which files define the current CafeKit runtime?" --repo
-$hapo-brainstorm Explore approaches for a Google Meet transcript extension
-$hapo-specs Build a Google Meet transcript extension with AI summaries
-$hapo-develop meet-transcript-mvp
-$hapo-test meet-transcript-mvp --full
-$hapo-code-review meet-transcript-mvp --pending
+$cf-ask "Which files define the current CafeKit runtime?" --repo
+$cf-scout "Find the runtime entrypoints for skill installation"
+$cf-brainstorm Explore approaches for a Google Meet transcript extension
+$cf-research Compare current transcript storage options for this repository
+$cf-specs Build a Google Meet transcript extension with AI summaries
+$cf-develop meet-transcript-mvp
+$cf-test meet-transcript-mvp --full
+$cf-code-review meet-transcript-mvp --pending
 ```
 
 Reconstruct as-is docs from a legacy codebase:
 
 ```bash
-/hapo:docs --reconstruct apps/legacy-admin
+/cf:docs --reconstruct apps/legacy-admin
 ```
 
-The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/hapo:specs`.
+The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/cf:specs`.
 
 ## Codex hook safety
 
@@ -215,9 +304,9 @@ specs/<feature-name>/
 └── task-NN-<slug>.md
 ```
 
-The process-first workflow has three human decision gates. `hapo:specs` opens
+The process-first workflow has three human decision gates. `cf:specs` opens
 C1 to fix scope before authoring and C2 to resolve adversarial findings, then
-stops. A later explicit `hapo:develop` invocation executes the tasks and
+stops. A later explicit `cf:develop` invocation executes the tasks and
 presents C3 for closeout only after real execution proof. Each task has one
 `Status:` field and keeps its canonical `## Receipt` inline, including the
 exact Verification Plan command, `Exit: 0`, `Verification: PASS`,

package/bin/__tests__/codex-hooks-ownership.test.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// `.codex/hooks.json` is a shared configuration file, not a CafeKit payload. It used to be
+// copied verbatim, so a single user-added hook turned the whole file into a user-modified
+// artifact: a normal install then preserved CafeKit's stale hooks, and `--force-overwrite`
+// destroyed the user's. These tests pin the merge that replaced that copy, mirroring how
+// `.claude/settings.json` has always been handled.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
+const TEMPLATE = path.join(PACKAGE_ROOT, 'src/codex/hooks.json');
+const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
+const { hookScript } = require(path.join(PACKAGE_ROOT, 'bin/phases/codex-hooks.js'));
+
+const USER_STOP_COMMAND = 'node "$(git rev-parse --show-toplevel)/scripts/my-own-stop.js"';
+const USER_PRETOOL_COMMAND = 'echo user-owned-pretooluse';
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-hooks-own-'));
+  try {
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, extraArgs = []) {
+  return spawnSync(
+    process.execPath,
+    [INSTALLER, '--platform', 'codex', '--yes', ...extraArgs],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, PATH: '/usr/bin:/bin' } }
+  );
+}
+
+function hooksPath(root) {
+  return path.join(root, '.codex', 'hooks.json');
+}
+
+function readHooks(root) {
+  return JSON.parse(fs.readFileSync(hooksPath(root), 'utf8'));
+}
+
+/** Every handler across every event, flattened. */
+function allHandlers(config) {
+  return Object.values(config.hooks || {})
+    .flatMap((groups) => (Array.isArray(groups) ? groups : []))
+    .flatMap((group) => (Array.isArray(group?.hooks) ? group.hooks : []));
+}
+
+function allCommands(config) {
+  return allHandlers(config).map((handler) => handler?.command).filter(Boolean);
+}
+
+/** The CafeKit hook scripts the template registers, per event. */
+function managedScripts() {
+  const template = JSON.parse(fs.readFileSync(TEMPLATE, 'utf8'));
+  const byEvent = {};
+  for (const [eventName, groups] of Object.entries(template.hooks || {})) {
+    byEvent[eventName] = groups
+      .flatMap((group) => group.hooks || [])
+      .map((handler) => hookScript(handler.command))
+      .filter(Boolean);
+  }
+  return byEvent;
+}
+
+/** Add two hooks CafeKit does not author: one under an event it owns, one under a new event. */
+function addUserHooks(root) {
+  const config = readHooks(root);
+  config.hooks.Stop.push({ matcher: '*', hooks: [{ type: 'command', command: USER_STOP_COMMAND }] });
+  config.hooks.PreToolUse.push({ matcher: 'Bash', hooks: [{ type: 'command', command: USER_PRETOOL_COMMAND }] });
+  fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+test('a fresh install registers every CafeKit hook under its own event', () => {
+  inTempProject((root) => {
+    const result = install(root);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+
+    const installed = readHooks(root);
+    for (const [eventName, scripts] of Object.entries(managedScripts())) {
+      const registered = (installed.hooks[eventName] || [])
+        .flatMap((group) => group.hooks || [])
+        .map((handler) => hookScript(handler.command))
+        .filter(Boolean);
+      for (const script of scripts) {
+        assert.ok(registered.includes(script), `${script} missing from ${eventName}`);
+      }
+    }
+  });
+});
+
+test('a reinstall preserves user-added hooks instead of overwriting them', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    addUserHooks(root);
+
+    const second = install(root);
+    assert.equal(second.status, 0, `${second.stdout}\n${second.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(commands.includes(USER_STOP_COMMAND), 'user Stop hook was erased by the reinstall');
+    assert.ok(commands.includes(USER_PRETOOL_COMMAND), 'user PreToolUse hook was erased by the reinstall');
+  });
+});
+
+test('--force-overwrite does not destroy hooks CafeKit did not author', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    addUserHooks(root);
+
+    const forced = install(root, ['--force-overwrite']);
+    assert.equal(forced.status, 0, `${forced.stdout}\n${forced.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(commands.includes(USER_STOP_COMMAND), '--force-overwrite erased the user Stop hook');
+    assert.ok(commands.includes(USER_PRETOOL_COMMAND), '--force-overwrite erased the user PreToolUse hook');
+  });
+});
+
+test('repeated installs never duplicate a CafeKit hook', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+    const afterFirst = allHandlers(readHooks(root)).length;
+
+    assert.equal(install(root).status, 0);
+    assert.equal(install(root).status, 0);
+
+    const config = readHooks(root);
+    assert.equal(allHandlers(config).length, afterFirst, 'a reinstall added handlers that were already registered');
+
+    // Uniqueness is per event, not global: state.cjs and completion-authority.cjs each
+    // register under several events by design.
+    for (const [eventName, groups] of Object.entries(config.hooks)) {
+      const scripts = groups
+        .flatMap((group) => group.hooks || [])
+        .map((handler) => hookScript(handler.command))
+        .filter(Boolean);
+      assert.equal(
+        new Set(scripts).size, scripts.length,
+        `duplicate hook scripts under ${eventName}: ${scripts.join(', ')}`
+      );
+    }
+  });
+});
+
+test('a hook the user moved to another event is not re-added to the one CafeKit chose', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    // Move a CafeKit hook out of the group the template put it in, the way a user editing
+    // matchers would. Re-adding it on the next install would fire it twice.
+    const config = readHooks(root);
+    let moved = null;
+    for (const group of config.hooks.PreToolUse) {
+      const index = (group.hooks || []).findIndex((handler) => hookScript(handler.command) === 'inspect-block.cjs');
+      if (index >= 0) { moved = group.hooks.splice(index, 1)[0]; break; }
+    }
+    assert.ok(moved, 'fixture expects inspect-block.cjs under PreToolUse');
+    config.hooks.PreToolUse.push({ matcher: 'Read|Grep', hooks: [moved] });
+    fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+
+    assert.equal(install(root).status, 0);
+
+    const scripts = allCommands(readHooks(root)).map(hookScript).filter(Boolean);
+    assert.equal(
+      scripts.filter((script) => script === 'inspect-block.cjs').length, 1,
+      'the moved hook was re-added under its original matcher'
+    );
+  });
+});
+
+test('obsolete CafeKit hooks are pruned while similarly named foreign hooks stay', () => {
+  const obsolete = MANIFEST.obsolete.settingsHookCommandSubstrings;
+  assert.ok(obsolete.length > 0, 'fixture requires at least one retired hook substring');
+
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    const config = readHooks(root);
+    const retired = `node ".codex/${obsolete[0]}"`;
+    const foreign = 'node "scripts/my-skill-router.cjs"';
+    config.hooks.UserPromptSubmit.push({
+      matcher: '*',
+      hooks: [{ type: 'command', command: retired }, { type: 'command', command: foreign }]
+    });
+    fs.writeFileSync(hooksPath(root), `${JSON.stringify(config, null, 2)}\n`);
+
+    const second = install(root);
+    assert.equal(second.status, 0, `${second.stdout}\n${second.stderr}`);
+
+    const commands = allCommands(readHooks(root));
+    assert.ok(!commands.includes(retired), 'retired CafeKit hook survived the prune');
+    assert.ok(commands.includes(foreign), 'prune removed a hook CafeKit never authored');
+  });
+});
+
+test('a malformed hooks.json is reported and left byte-identical, never overwritten', () => {
+  inTempProject((root) => {
+    fs.mkdirSync(path.join(root, '.codex'), { recursive: true });
+    const broken = '{ "hooks": { "Stop": [ }\n';
+    fs.writeFileSync(hooksPath(root), broken);
+
+    const result = install(root);
+    assert.notEqual(result.status, 0, 'a malformed hooks.json must fail the install, not pass silently');
+    assert.match(`${result.stdout}${result.stderr}`, /not valid JSON/);
+    assert.equal(fs.readFileSync(hooksPath(root), 'utf8'), broken, 'the malformed file was overwritten');
+  });
+});
+
+test('a dry run reports the merge without writing hooks.json', () => {
+  inTempProject((root) => {
+    const result = install(root, ['--dry-run']);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.match(result.stdout, /Codex hooks/);
+    assert.equal(fs.existsSync(hooksPath(root)), false, 'a dry run wrote hooks.json');
+  });
+});
+
+test('hooks.json stays outside the ownership manifest, like settings.json', () => {
+  inTempProject((root) => {
+    assert.equal(install(root).status, 0);
+
+    const manifestPath = path.join(root, '.codex', 'cafekit-manifest.json');
+    assert.equal(fs.existsSync(manifestPath), true, 'the install manifest is missing');
+    const tracked = Object.keys(JSON.parse(fs.readFileSync(manifestPath, 'utf8')).files || {});
+    assert.ok(
+      !tracked.some((file) => file.endsWith('hooks.json')),
+      'hooks.json is tracked as a payload file, so a user edit would be classified user-modified again'
+    );
+  });
+});