@haposoft/cafekit 0.14.1 → 0.15.0

package/src/codex/hooks/task-scaffold-guard.cjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+
+function addedFiles(toolName, input) {
+  if (toolName === 'Write') {
+    return [input.file_path || input.filePath || input.path || ''].filter(Boolean);
+  }
+  if (toolName !== 'apply_patch') return [];
+  const patch = typeof input.command === 'string'
+    ? input.command
+    : typeof input.patch === 'string' ? input.patch : '';
+  return [...patch.matchAll(/^\*\*\* Add File:\s+(.+)$/gm)]
+    .map((match) => match[1].trim());
+}
+
+function projectRelative(filePath, projectRoot, sessionCwd) {
+  const absolute = path.isAbsolute(filePath)
+    ? path.normalize(filePath)
+    : path.resolve(sessionCwd, filePath);
+  return path.relative(projectRoot, absolute).replace(/\\/g, '/');
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  const candidates = addedFiles(payload.tool_name || '', payload.tool_input || {});
+  const taskFile = candidates
+    .map((requested) => ({
+      requested,
+      relative: projectRelative(requested, projectRoot, sessionCwd)
+    }))
+    .find(({ relative }) => (
+      /^specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(relative)
+    ));
+  if (!taskFile) process.exit(0);
+  if (runtime.spec?.scaffold_guard === false) process.exit(0);
+
+  const scaffold = path.join(projectRoot, '.codex', 'scripts', 'spec-scaffold.cjs');
+  if (!fs.existsSync(scaffold)) process.exit(0);
+
+  const feature = taskFile.relative.split('/')[1];
+  const command = sessionCwd === projectRoot
+    ? `node .codex/scripts/spec-scaffold.cjs ${feature}`
+    : `node ${JSON.stringify(scaffold)} ${feature}`;
+  process.stderr.write(
+    'TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n'
+    + `Blocked Write: ${taskFile.requested}\n\n`
+    + 'Generate the stubs, then fill their {{...}} placeholders with apply_patch:\n'
+    + `  ${command} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n`
+  );
+  process.exit(2);
+} catch (error) {
+  logCrash('task-scaffold-guard', error);
+}

package/src/codex/hooks.json

@@ -0,0 +1,122 @@
+{
+  "description": "CafeKit project-local lifecycle hooks for Codex CLI. Review and trust with /hooks.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/session.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/session.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/docs-sync.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/docs-sync.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/agent.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/agent.cjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/rules.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/rules.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-state.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-block.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-block.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/inspect-block.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/inspect-block.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/task-scaffold-guard.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/task-scaffold-guard.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent|spawn_agent|update_plan|task|Task|TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-gate.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/codex/rules/hook-protocols.md

@@ -0,0 +1,32 @@
+# Hook Protocols
+
+Hooks are instruction boundaries. Do not bypass or work around them.
+
+## Privacy Block Hook
+
+Codex cannot pause a blocked tool call for an interactive permission question.
+CafeKit therefore denies the sensitive access and emits one exact approval
+phrase tied to the current session, requested path, tool, and expiry.
+
+Required flow:
+
+1. Stop the blocked access and show the user the hook's reason.
+2. Ask the user to send the exact approval phrase if they want one retry.
+3. Do not write, repeat as a user message, or otherwise simulate that phrase.
+4. Retry only after a later real user prompt exactly matches it.
+5. Use the resulting token once, only for the originally blocked operation.
+
+Never use another command, path, encoding, subprocess, or side channel to read a
+privacy-blocked file without that explicit approval.
+
+## State And Spec Hooks
+
+- If a hook reports state drift, run the appropriate sync or audit flow before continuing.
+- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists.
+- Do not mark a task `done` unless the matching task file contains a valid verification receipt.
+
+## Hook Failure Handling
+
+- Treat hook errors as blockers when they affect safety, privacy, or task state.
+- Record the blocker in the task or spec state when relevant.
+- If hook output is malformed, stop and report the exact failure instead of guessing.

package/src/codex/rules/state-sync.md

@@ -0,0 +1,41 @@
+# Tollgate Protocol (State Sync)
+
+## Sources Of Truth
+
+Spec-driven work persists state in two synchronized layers:
+
+1. `spec.json` tracks phase, overall status, and `task_registry`.
+2. `tasks/task-*.md` tracks the human-readable checklist and verification receipt.
+
+## Sync-back Rule
+
+Before reporting a task completed or blocked:
+
+### On success
+
+1. Update `spec.json` only after verification. Keep `current_phase`,
+   `task_files`, status, timestamps, and the matching `task_registry` entry accurate.
+2. Update the matching task Markdown status, checkboxes, completion criteria,
+   and `## Evidence` receipt from the current verification run.
+3. Update native plan or task state when the active Codex session provides it,
+   but never use chat-only state as a substitute for the files above.
+
+### On block after repeated attempts
+
+1. Set the spec and matching registry entry to `blocked`, with the root cause and timestamp.
+2. Mark the task Markdown `blocked` and record the evidence.
+3. Tell the user or orchestrator exactly what external input or state change is required.
+
+New specs use `in_progress`; legacy `in-progress` may be read but not emitted.
+Never let `task_registry` disagree with its task Markdown file.
+
+## Completion Gate
+
+The Stop hook checks newly completed tasks. Each requires:
+
+- `Status: done`;
+- a non-placeholder `## Evidence` section with a command block or PASS/FAIL result;
+- a non-empty `task_registry[path].completed_at`.
+
+The first run seeds completion history without blocking. Humans can disable the
+gate with `"spec": { "completion_gate": false }` in `.codex/runtime.json`.

package/src/codex/runtime.json

@@ -0,0 +1,28 @@
+{
+  "privacyBlock": true,
+  "inspect": {
+    "enabled": true
+  },
+  "docs": {
+    "maxLoc": 800
+  },
+  "paths": {
+    "docs": "docs",
+    "specs": "specs",
+    "plans": "plans"
+  },
+  "spec": {
+    "scaffold_guard": true,
+    "completion_gate": true,
+    "tollgate": true
+  },
+  "develop": {
+    "parallel": true
+  },
+  "locale": {
+    "thinkingLanguage": null,
+    "responseLanguage": null
+  },
+  "hooks": {},
+  "assertions": []
+}

package/src/opencode/plugins/docs-sync.ts

@@ -71,27 +71,21 @@ function currentSourceHash(cwd: string): string {
 
 function buildMissingDocsBanner(): string {
   return [
-    "### 🔴 URGENT SYSTEM ACTION: MISSING DOCUMENTATION 🔴",
-    "> BẮT BUỘC (MANDATORY): Hệ thống phát hiện dự án đã có Source Code nhưng thư mục `docs/` chưa tồn tại.",
-    "> Nhiệm vụ ĐẦU TIÊN của bạn trong session này là đọc hiểu mã nguồn hiện tại và tạo ra các tài liệu tiêu chuẩn:",
-    "> 1. `docs/system-architecture.md` (Kiến trúc hệ thống, phân tích flow)",
-    "> 2. `docs/project-overview-pdr.md` (Tổng quan, mục tiêu, tính năng)",
-    "> 3. Khởi tạo file hidden `docs/.sync_hash` để theo dõi cập nhật.",
-    "> ",
-    '> LƯU Ý BẮT BUỘC: Bạn phải chạy lệnh Git này trong Terminal để lấy Hash Code mới nhất: `git log -1 --format="%H" -- . ":(exclude)docs"`',
-    "> Sau đó ghi chuẩn giá trị Hash đó vào file `docs/.sync_hash`.",
+    "### Missing docs/",
+    "> Source exists but `docs/` does not. Create baseline docs first:",
+    "> 1. `docs/system-architecture.md` — system architecture and flows",
+    "> 2. `docs/project-overview-pdr.md` — overview, goals, features",
+    '> 3. Write current hash to `docs/.sync_hash` via `git log -1 --format="%H" -- . ":(exclude)docs"`',
   ].join("\n");
 }
 
 function buildStaleDocsBanner(currentHash: string, lastSyncHash: string): string {
   return [
-    "### 🔄 CONTINUOUS DOCS SYNC REQUIRED 🔄",
-    `> Source Code vừa có sự thay đổi mới (Git Hash: \`${currentHash}\`) kể từ lần đồng bộ Docs cuối cùng (\`${lastSyncHash || "Chưa gán"}\`).`,
-    "> YÊU CẦU TRƯỚC KHI LÀM THÊM TÍNH NĂNG:",
-    `> 1. Rà soát file bị thay đổi gần đây (dùng \`git diff ${lastSyncHash} ${currentHash}\` hoặc \`git log\`).`,
-    "> 2. Cập nhật lại `docs/system-architecture.md` hoặc các chuẩn code nếu cần thiết.",
-    "> 3. Cập nhật Changelog (nhật ký thay đổi).",
-    `> 4. KHI HOÀN TẤT, BẠN PHẢI GHI ĐÈ GIÁ TRỊ SAU: \`${currentHash}\` VÀO FILE \`docs/.sync_hash\` ĐỂ CHỐT TRẠNG THÁI HIỆN TẠI.`,
+    "### Docs sync needed",
+    `> Source changed (\`${currentHash}\`) since last docs sync (\`${lastSyncHash || "none"}\`).`,
+    `> 1. Review recent changes (\`git diff ${lastSyncHash} ${currentHash}\` or \`git log\`).`,
+    "> 2. Update architecture/code-standards docs and changelog as needed.",
+    `> 3. Write \`${currentHash}\` to \`docs/.sync_hash\` when done.`,
   ].join("\n");
 }
 

package/src/claude/archive-command/code/SKILL.md

@@ -1,55 +0,0 @@
----
-name: hapo:code
-description: Implement the next approved spec task and then hand off to hapo:test and hapo:review.
-version: 1.0.0
-argument-hint: <feature-name>
----
-
-# Code
-
-Implement the next pending task from an approved spec instead of coding from memory.
-
-## Usage
-
-```bash
-/hapo:code <feature-name>
-```
-
-## Load First
-
-- `references/execution-loop.md`
-- `.specs/$ARGUMENTS/tasks.md`
-- `.specs/$ARGUMENTS/design.md`
-- `.specs/$ARGUMENTS/requirements.md`
-
-## Execute
-
-1. Read `.specs/$ARGUMENTS/tasks.md` and identify the next pending task.
-2. Read the related context from `design.md` and `requirements.md`.
-3. Implement only that task. Keep scope tight.
-4. Follow the project standards already present in the repo.
-5. Update task status in the spec artifact if the workflow supports it.
-6. Hand off immediately to:
-   - `/hapo:test`
-   - `/hapo:review`
-
-## Output
-
-Return:
-- implemented task name
-- touched files
-- blockers or follow-up items
-- explicit handoff to `/hapo:test` and `/hapo:review`
-
-## Rules
-
-- Do not implement multiple major tasks in one pass.
-- Stop if `tasks.md` is missing.
-- Prefer existing patterns over new abstractions.
-- Keep the work aligned to the spec.
-
-## Related
-
-- Command: `/code`
-- Previous skill: `/hapo:spec-tasks`
-- Next skills: `/hapo:test`, `/hapo:review`

package/src/claude/archive-command/code/references/execution-loop.md

@@ -1,21 +0,0 @@
-# Execution Loop
-
-## Goal
-
-Implement one approved task at a time and immediately validate it.
-
-## Loop
-
-1. Read the next pending task in `tasks.md`.
-2. Read the matching context in `design.md` and `requirements.md`.
-3. Implement only that task.
-4. Run `/hapo:test`.
-5. Run `/hapo:review`.
-6. Move to the next task only after the current pass is clear.
-
-## Guardrails
-
-- Keep scope tight.
-- Prefer existing project patterns.
-- Do not batch multiple major tasks into one pass.
-- Stop and report blockers instead of guessing.

package/src/claude/archive-command/code.md

@@ -1,17 +0,0 @@
----
-name: code
-description: Implement approved work from specification tasks and then hand off to test and review.
-allowed-tools: Read, Glob, Grep, Edit, Write, Bash
-argument-hint: <feature-name>
----
-
-# /code - Implement from spec tasks
-
-Use this command after /spec-tasks.
-
-1. Read `.specs/$ARGUMENTS/tasks.md` and identify the next pending task.
-2. Implement only that task following project standards.
-3. Run `/test`.
-4. Run `/review`.
-
-Preferred flow: /spec-init -> /spec-requirements -> /spec-design -> /spec-tasks -> /code -> /test -> /review