@haposoft/cafekit 0.14.1 → 0.15.0

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

@@ -39,24 +39,20 @@ try {
 
   const lines = [];
 
-  // Trường hợp 1: Có Code nhưng chưa có thư mục docs
+  // Case 1: source present but docs/ missing
   if (!fs.existsSync(docsDir)) {
     lines.push('');
-    lines.push('### 🔴 URGENT SYSTEM ACTION: MISSING DOCUMENTATION 🔴');
-    lines.push(`> 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.`);
-    lines.push(`> 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:`);
-    lines.push(`> 1. \`docs/system-architecture.md\` (Kiến trúc hệ thống, phân tích flow)`);
-    lines.push(`> 2. \`docs/project-overview-pdr.md\` (Tổng quan, mục tiêu, tính năng)`);
-    lines.push(`> 3. Khởi tạo file hidden \`docs/.sync_hash\` để theo dõi cập nhật.`);
-    lines.push(`> `);
-    lines.push(`> 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"\``);
-    lines.push(`> Sau đó ghi chuẩn giá trị Hash đó vào file \`docs/.sync_hash\`.`);
+    lines.push('### Missing docs/');
+    lines.push('> Source exists but `docs/` does not. Create baseline docs first:');
+    lines.push('> 1. `docs/system-architecture.md` — system architecture and flows');
+    lines.push('> 2. `docs/project-overview-pdr.md` — overview, goals, features');
+    lines.push('> 3. Write current hash to `docs/.sync_hash` via `git log -1 --format="%H" -- . ":(exclude)docs"`');
     lines.push('');
-  } 
-  // Trường hợp 2: Có Code, đã có Docs. Kiểm tra Continuous Sync
+  }
+  // Case 2: docs exist — check continuous sync vs source-only git hash
   else {
     try {
-      // Lấy hash của lần thay đổi SOURCE CODE gần nhất (Bỏ qua những commit chỉ sửa docs)
+      // Latest SOURCE-only hash (ignore docs-only commits)
       const currentHash = execSync('git log -1 --format="%H" -- . ":(exclude)docs"', { 
         cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] 
       }).trim();
@@ -69,18 +65,16 @@ try {
 
         if (lastSyncHash !== currentHash) {
           lines.push('');
-          lines.push('### 🔄 CONTINUOUS DOCS SYNC REQUIRED 🔄');
-          lines.push(`> 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'}\`).`);
-          lines.push(`> YÊU CẦU TRƯỚC KHI LÀM THÊM TÍNH NĂNG:`);
-          lines.push(`> 1. Rà soát file bị thay đổi gần đây (dùng \`git diff ${lastSyncHash} ${currentHash}\` hoặc \`git log\`).`);
-          lines.push(`> 2. Cập nhật lại \`docs/system-architecture.md\` hoặc các chuẩn code nếu cần thiết.`);
-          lines.push(`> 3. Cập nhật Changelog (nhật ký thay đổi).`);
-          lines.push(`> 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.`);
+          lines.push('### Docs sync needed');
+          lines.push(`> Source changed (\`${currentHash}\`) since last docs sync (\`${lastSyncHash || 'none'}\`).`);
+          lines.push(`> 1. Review recent changes (\`git diff ${lastSyncHash} ${currentHash}\` or \`git log\`).`);
+          lines.push('> 2. Update architecture/code-standards docs and changelog as needed.');
+          lines.push(`> 3. Write \`${currentHash}\` to \`docs/.sync_hash\` when done.`);
           lines.push('');
         }
       }
     } catch (e) {
-      // Git chưa init hoặc chưa có commit nào thì im lặng fail-open
+      // Git not initialized or no commits — fail-open
     }
   }
 

package/src/claude/hooks/inspect-block.cjs

@@ -21,7 +21,7 @@ try {
   // Directories that should never be read (too large / irrelevant to LLM)
   const BLOCKED_DIRS = [
     'node_modules', 'dist', 'build', '.next', '.nuxt', '.output',
-    '__pycache__', '.venv', 'venv', '.env',
+    '__pycache__', '.venv', 'venv',
     'vendor', 'target',
     '.git', 'coverage', '.nyc_output',
   ];

package/src/claude/hooks/lib/config.cjs

@@ -52,11 +52,6 @@ const DEFAULT_CONFIG = {
     packageManager: 'auto',
     framework: 'auto'
   },
-  skills: {
-    research: {
-      useGemini: true  // Toggle Gemini CLI usage in research skill
-    }
-  },
   assertions: [],
   statusline: 'full',
   statuslineColors: true,

package/src/claude/hooks/privacy-block.cjs

@@ -7,12 +7,11 @@
  * Claude Code CLI privacy gate for sensitive files.
  *
  * Runtime contract:
- * - Non-bash file access to sensitive files is blocked with a JSON marker
- * - Assistant must use AskUserQuestion with that JSON payload
- * - If user approves, assistant should read via `bash cat "file"`
- * - Bash access is allowed with a warning to enable the approved follow-up path
+ * - Sensitive access returns Claude Code's native PreToolUse "ask" decision
+ * - The same decision applies to direct tools and Bash commands
+ * - Symlinks are classified by their resolved target before their alias
  *
- * Exit: 0 = allow, 2 = block
+ * Exit: 0 (the JSON hook output carries the permission decision)
  */
 
 try {
@@ -20,7 +19,7 @@ try {
   const path = require('path');
 
   const RESTRICTED_PATTERNS = [
-    /^\.env(\.|$)/i,
+    /^\.env(?:[.\[*?{]|$)/i,
     /^credentials/i,
     /secrets?\.(ya?ml|json)$/i,
     /\.pem$/i,
@@ -66,22 +65,28 @@ try {
    * when the path cannot be resolved (missing file, broken link) — fail-open to
    * the original-path check in that case.
    */
-  function resolveTarget(filePath) {
+  function resolveTarget(filePath, cwd) {
     try {
-      return fs.realpathSync(filePath);
+      const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+      return fs.realpathSync(requested);
     } catch {
       return null;
     }
   }
 
   function extractBashPaths(command) {
-    const paths = [];
-    const regex = /(?:cat|less|more|head|tail|source|\.)\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))/g;
-    let match;
-    while ((match = regex.exec(command)) !== null) {
-      paths.push(match[1] || match[2] || match[3]);
+    const paths = new Set();
+    // Quotes are delimiters rather than grouped tokens so nested shell
+    // commands such as `bash -c 'cat .env'` cannot hide the sensitive path.
+    const tokens = command.split(/[\s|;&<>"']+/).filter(Boolean);
+    for (const token of tokens) {
+      const cleaned = token.replace(/^["'()`]+|["'(),]+$/g, '');
+      for (const candidate of cleaned.split('=')) {
+        const value = candidate.replace(/^["'()`]+|["'(),]+$/g, '');
+        if (value && (isSensitive(value) || isSafe(value))) paths.add(value);
+      }
     }
-    return paths;
+    return [...paths];
   }
 
   function extractPaths(toolName, input) {
@@ -107,42 +112,15 @@ try {
     return paths.filter(Boolean);
   }
 
-  function formatBlockMessage(filePath) {
+  function askForPermission(filePath) {
     const basename = path.basename(filePath);
-    const promptData = {
-      type: 'PRIVACY_PROMPT',
-      file: filePath,
-      basename,
-      question: {
-        header: 'File Access',
-        text: `I need to read "${basename}" which may contain sensitive data (API keys, passwords, tokens). Do you approve?`,
-        options: [
-          {
-            label: 'Yes, approve access',
-            description: `Allow reading ${basename} this time`
-          },
-          {
-            label: 'No, skip this file',
-            description: 'Continue without accessing this file'
-          }
-        ]
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason: `Sensitive file access requires approval: ${basename}`
       }
-    };
-
-    return [
-      'NOTE: This is not an error. This block protects sensitive data.',
-      '',
-      `PRIVACY BLOCK: Sensitive file access requires user approval`,
-      `File: ${filePath}`,
-      '',
-      '@@PRIVACY_PROMPT_START@@',
-      JSON.stringify(promptData, null, 2),
-      '@@PRIVACY_PROMPT_END@@',
-      '',
-      'Claude Code follow-up:',
-      `- If approved: use bash to read: cat "${filePath}"`,
-      '- If denied: continue without this file'
-    ].join('\n');
+    }) + '\n');
   }
 
   const stdin = fs.readFileSync(0, 'utf8').trim();
@@ -160,22 +138,21 @@ try {
   if (!paths.length) process.exit(0);
 
   for (const filePath of paths) {
-    // Check the requested path and, when it is a symlink, its real target.
-    const target = resolveTarget(filePath);
-    const candidates = target && target !== filePath ? [filePath, target] : [filePath];
-
-    // An exemption on either name wins (e.g. a symlink to .env.example).
-    if (candidates.some(isSafe)) continue;
-    // Sensitive if the requested path OR its symlink target is sensitive.
-    if (!candidates.some(isSensitive)) continue;
-
-    if (toolName === 'Bash') {
-      console.error(`WARN: Privacy-sensitive file access via bash allowed for approved follow-up: ${path.basename(filePath)}`);
-      process.exit(0);
+    const target = resolveTarget(filePath, cwd);
+
+    // The real target is authoritative: an exempt-looking alias must not hide
+    // a sensitive target, while a real .env.example target remains safe.
+    if (target) {
+      if (isSensitive(target) && !isSafe(target)) {
+        askForPermission(filePath);
+        process.exit(0);
+      }
+      if (isSafe(target)) continue;
     }
 
-    console.error(formatBlockMessage(filePath));
-    process.exit(2);
+    if (isSafe(filePath) || !isSensitive(filePath)) continue;
+    askForPermission(filePath);
+    process.exit(0);
   }
 
   process.exit(0);

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

@@ -84,11 +84,12 @@ try {
   const newlyDone = Object.keys(taskRegistry).filter((tp) =>
     (taskRegistry[tp]?.status || 'pending') === 'done' && featureCache[tp] !== 'done'
   );
-  if (newlyDone.length === 0) process.exit(0);
-
   // /m so ^ matches line starts (Evidence is never at byte 0 of the file).
+  // legacy heading aliases: read-compat only, no longer advertised
   const EVID_RE = /^#{2,3}\s+(Evidence|Task Test Plan & Verification Evidence|Verification & Evidence)\b/m;
-  const PROOF_RE = /(PASS|FAIL|exit code|passed|✓)/;
+  const PASS_MARKER_RE = /^\s*Verification:\s*PASS\s*$/m;
+  const LEGACY_SUCCESS_RE = /^\s*(?:PASS(?:ED)?|✓)(?:\s*:|$)|exit\s+code\s*[:=]?\s*0\b/im;
+  const EXPLICIT_FAILURE_RE = /\bFAIL(?:ED|URE|URES|ING)?\b|tests?\s+failed|exit\s+code\s*[:=]?\s*[1-9]\d*|\b0\s+tests?\b/i;
 
   /** Body of first Evidence heading until next same-or-higher heading. */
   function evidenceBody(text) {
@@ -122,12 +123,20 @@ try {
     const body = evidenceBody(text);
     if (body === null || !EVID_RE.test(text)) {
       fails.push('b');
-    } else if (/\{\{[^}]+\}\}/.test(body) || !(/```/.test(body) || PROOF_RE.test(body))) {
+    } else if (
+      /\{\{[^}]+\}\}/.test(body) ||
+      EXPLICIT_FAILURE_RE.test(body) ||
+      !(PASS_MARKER_RE.test(body) || LEGACY_SUCCESS_RE.test(body))
+    ) {
       fails.push('c');
     }
 
     const at = taskRegistry[taskPath]?.completed_at;
-    if (typeof at !== 'string' || at.trim() === '') fails.push('d');
+    if (
+      typeof at !== 'string' ||
+      !/^\d{4}-\d{2}-\d{2}T/.test(at) ||
+      Number.isNaN(Date.parse(at))
+    ) fails.push('d');
     return fails;
   }
 
@@ -135,7 +144,8 @@ try {
     .map((tp) => ({ taskPath: tp, fails: checkReceipt(tp) }))
     .filter((f) => f.fails.length > 0);
 
-  // Leave failing newly-done at old cache status so the gate re-fires next Stop.
+  // Always persist status transitions, including done → pending. Leave failing
+  // newly-done tasks at their old status so the gate re-fires next Stop.
   try {
     const nextFeature = { ...featureCache, ...currentStatuses };
     for (const { taskPath } of failures) {
@@ -147,6 +157,7 @@ try {
     fs.writeFileSync(cacheFile, JSON.stringify(cache));
   } catch { /* fail-open */ }
 
+  if (newlyDone.length === 0) process.exit(0);
   if (failures.length === 0) process.exit(0);
 
   const lines = [
@@ -155,7 +166,7 @@ try {
   for (const { taskPath, fails } of failures) {
     lines.push(`- \`${taskPath}\`: failed check(s) ${fails.join(', ')}`);
     lines.push(
-      `  Fix: add a verification receipt to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`: commands run + outcomes, then re-sync spec.json`
+      `  Fix: add \`Verification: PASS\` plus commands and successful outcomes to \`## Evidence\` in \`specs/${featureName}/${taskPath}\`, then re-sync spec.json`
     );
   }
   process.stdout.write(JSON.stringify({ decision: 'block', reason: lines.slice(0, 8).join('\n') }) + '\n');

package/src/claude/hooks/spec-state.cjs

@@ -30,6 +30,10 @@ try {
     if (fs.existsSync(p)) runtime = JSON.parse(fs.readFileSync(p, 'utf8'));
   } catch { /* ignore */ }
 
+  // Reminder toggle — same key the OpenCode spec-state plugin honors.
+  // (The Stop completion gate has its own toggle: spec.completion_gate.)
+  if (runtime.spec && runtime.spec.tollgate === false) process.exit(0);
+
   const baseDir   = process.env.PROJECT_ROOT || cwd;
   const specsPath = path.join(baseDir, runtime.paths?.specs || 'specs');
 

package/src/claude/hooks/state.cjs

@@ -120,19 +120,29 @@ try {
       }
     }
 
+    const changed = [];
     try {
       const diff = execSync('git diff --name-only HEAD', {
         encoding: 'utf8',
         timeout: 3000,
         stdio: ['pipe', 'pipe', 'pipe']
       }).trim();
+      if (diff) changed.push(...diff.split('\n'));
+    } catch {
+      // A repository without HEAD can still report untracked files below.
+    }
 
-      if (diff) {
-        data.modifiedFiles = diff.split('\n').slice(0, MAX_MODIFIED_FILES_DISPLAY);
-      }
+    try {
+      const untracked = execSync('git ls-files --others --exclude-standard', {
+        encoding: 'utf8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'pipe']
+      }).trim();
+      if (untracked) changed.push(...untracked.split('\n'));
     } catch {
       // fail-open
     }
+    data.modifiedFiles = [...new Set(changed)].slice(0, MAX_MODIFIED_FILES_DISPLAY);
 
     return data;
   }

package/src/claude/hooks/usage.cjs

@@ -8,6 +8,12 @@
  * Fetches Claude Code usage limits from Anthropic OAuth API and writes to cache.
  * Cache is read by status.cjs for statusline display.
  *
+ * ⚠ EXPERIMENTAL / UNDOCUMENTED API: api.anthropic.com/api/oauth/usage with the
+ * "oauth-2025-04-20" beta header is not a public contract and may break or
+ * change shape without notice. Every failure path degrades to
+ * status:"unavailable" (statusline hides the segment) — never block on it.
+ * Disable entirely with "usage": { "enabled": false } if it misbehaves.
+ *
  * Features:
  * - Cross-platform credential retrieval (macOS Keychain, file-based)
  * - Throttled API calls: 1 min (prompt) / 5 min (tool use)

package/src/claude/rules/orchestrator.md

@@ -23,7 +23,7 @@ Example prompt:
 ## Resource Constraints
 
 - Each subagent has a **200K token context window** — scope tasks to fit comfortably within it
-- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out
+- Spawning many parallel agents degrades system performance — check available CPU/memory before scaling out. For parallel implementation waves the cap is 3 concurrent agents by default, never more than 5 (each agent carries the 200K budget above)
 - Prefer fewer, well-scoped agents over many overlapping ones
 - Include system resource info (from hook injection) when delegating tasks so subagents can self-regulate
 
@@ -48,7 +48,7 @@ For implementation tasks, keep the chain explicit:
 2. Verify with `test-runner` using task files and exact evidence commands.
 3. Review with `code-auditor` using task files, design contracts, and the diff.
 
-Do not dispatch multiple implementation agents against the same files or same task. Parallelize only independent scopes with distinct file ownership.
+Do not dispatch multiple implementation agents against the same files or same task **within the same working tree**. Parallelize only independent scopes with distinct file ownership — the sanctioned pattern for parallel implementation is **worktree isolation** (one agent per task, each in its own git worktree) with a **single writer per file per wave** and orchestrator-only spec-state writes, per `skills/develop/references/parallel-waves.md`.
 
 ### Parallel (independent tasks)
 

package/src/claude/rules/skill-domain-routing.md

@@ -1,88 +1,29 @@
 # Skill Domain Routing
 
-Use this decision tree to choose domain skills from the installed CafeKit skill set. This is advisory routing, not an automatic hook.
-
-## Frontend And UI
-
-```text
-User wants to...
-├── choose style, color, layout, UX, design system       -> /hapo:frontend-design
-├── build React/TypeScript UI components                 -> /hapo:frontend-development
-├── optimize React/Next.js performance or rerenders      -> /hapo:react-best-practices
-├── apply deep UI/UX intelligence, visual polish         -> /hapo:ui-ux-pro-max
-└── test UI in browser                                   -> /hapo:web-testing or /hapo:agent-browser
-```
-
-Use `/hapo:react-best-practices` for performance/re-render patterns. Use `/hapo:frontend-development` for normal implementation.
-
-## Backend, Data, And Infrastructure
-
-```text
-User wants to...
-├── API, service, auth, database-backed feature          -> /hapo:backend-development
-├── deployment, Docker, Kubernetes, Cloudflare, CI/CD     -> /hapo:devops
-└── mobile apps, iOS, Android, React Native, Flutter     -> /hapo:mobile-development
-```
-
-## Codebase Understanding
-
-```text
-User wants to...
-├── answer questions from source code/docs/specs/config    -> /hapo:question
-├── find files, locate code, scan project structure       -> /hapo:inspect
-├── diagnose an error or failing check                    -> /hapo:debug
-├── understand possible side effects                      -> /hapo:inspect
-└── compare external approaches or best practices         -> /hapo:research
-```
-
-Local source truth comes from `/hapo:inspect`; external/current knowledge comes from `/hapo:research`.
-
-## Documentation
-
-```text
-User wants to...
-├── ask/answer documentation questions from source         -> /hapo:question
-├── create missing project docs                           -> /hapo:docs --init
-├── update docs after source changes                      -> /hapo:docs --update
-├── summarize codebase quickly                            -> /hapo:docs --summarize
-├── reconstruct as-is docs from legacy source code        -> /hapo:docs --reconstruct <scope>
-└── create a future feature spec                          -> /hapo:specs
-```
-
-Keep as-is reconstruction separate from future requirements. Reconstructed docs document current behavior; specs define requested changes.
-
-## Testing And Browser
-
-```text
-User wants to...
-├── run test suites, coverage, scoped verification        -> /hapo:test
-├── E2E/unit/integration/load/security/a11y strategy      -> /hapo:web-testing
-├── drive a browser with snapshots or Browserbase         -> /hapo:agent-browser
-└── Chrome DevTools/Puppeteer evidence                    -> /hapo:chrome-devtools
-```
-
-## Documents And Media
-
-```text
-User wants to...
-├── PowerPoint/slides                                     -> /hapo:pptx
-├── Word documents                                        -> /hapo:docx
-├── PDFs                                                  -> /hapo:pdf
-├── spreadsheets/CSV/XLSX                                 -> /hapo:xlsx
-└── image/audio/video/document multimodal analysis        -> /hapo:ai-multimodal
-```
-
-## Git And Release
-
-```text
-User wants to...
-├── commit, branch, tag, push, release prep               -> /hapo:git
-└── review before release                                 -> /hapo:code-review
-```
-
-## Usage Notes
-
-- Read the selected skill's `SKILL.md` before acting.
-- Do not activate a skill only because one keyword appears. Use the whole user intent.
-- If a task spans multiple domains, name the primary skill and mention the secondary skill in the plan.
-- If no domain skill fits, use the core CafeKit workflow in `skill-workflow-routing.md`.
+Advisory routing for installed domain skills (not an automatic hook). Read the selected skill's `SKILL.md` before acting.
+
+| Domain / intent | Skill |
+|---|---|
+| answer questions from source code/docs/specs/config | `/hapo:question` |
+| file discovery, structure, blast radius | `/hapo:inspect` |
+| style / layout / design system | `/hapo:frontend-design` |
+| React/TypeScript UI implementation | `/hapo:frontend-development` |
+| React/Next performance / re-renders | `/hapo:react-best-practices` |
+| deep UI/UX polish | `/hapo:ui-ux-pro-max` |
+| API, service, auth, database | `/hapo:backend-development` |
+| deploy / Docker / K8s / Cloudflare / CI | `/hapo:devops` |
+| mobile (RN / Flutter / iOS / Android) | `/hapo:mobile-development` |
+| docs init / update / summarize | `/hapo:docs --init` / `--update` / `--summarize` |
+| as-is reconstruction from legacy code | `/hapo:docs --reconstruct <scope>` |
+| future feature requirements | `/hapo:specs` |
+| run suites / scoped verification | `/hapo:test` |
+| E2E / load / a11y strategy | `/hapo:web-testing` |
+| browser snapshots / Browserbase | `/hapo:agent-browser` |
+| Chrome DevTools evidence | `/hapo:chrome-devtools` |
+| diagnose error / CI failure | `/hapo:debug` |
+| external best practices / tool compare | `/hapo:research` |
+| pptx / docx / pdf / xlsx / multimodal | `/hapo:pptx` / `docx` / `pdf` / `xlsx` / `ai-multimodal` |
+| commit / branch / release prep | `/hapo:git` |
+| review before release | `/hapo:code-review` |
+
+Pick one primary domain skill; name a secondary only when it changes execution. If none fit, use `skill-workflow-routing.md`.

package/src/claude/rules/skill-workflow-routing.md

@@ -4,92 +4,21 @@ Use this rule instead of automatic prompt routing. Read the user's intent, choos
 
 Do not inject or force a skill when the user explicitly asks for a direct answer, a specific command, or a different workflow.
 
-## Core Specification Workflow
+Claude Code selects skills from frontmatter descriptions; trust it for clear intents.
 
-```text
-/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
-```
-
-| User intent | Suggested start |
-|---|---|
-| ask about source code, docs, specs, config, dependencies, or external/current technical facts | `/hapo:question` |
-| vague request, missing acceptance criteria, unclear scope, stakeholder questions | ask one clarification or use `/hapo:brainstorm` |
-| unclear idea, possible approaches, scope tradeoffs | `/hapo:brainstorm` |
-| create requirements, design, task breakdown, validate spec | `/hapo:specs` |
-| implement an approved spec or a specific task file | `/hapo:develop` |
-| run tests, QA, runtime verification | `/hapo:test` |
-| review code quality, security, regressions, maintainability | `/hapo:code-review` |
-| commit, tag, push, branch, release prep | `/hapo:git` |
-
-## Bug And Incident Workflow
-
-```text
-/hapo:debug -> /hapo:hotfix -> /hapo:test -> /hapo:code-review
-```
-
-| User intent | Suggested start |
-|---|---|
-| diagnose why something fails, find root cause, inspect CI/logs | `/hapo:debug` |
-| fix a known bug after diagnosis, urgent regression, production issue | `/hapo:hotfix` |
-| verify the fix and affected behavior | `/hapo:test` |
-| check side effects before closeout | `/hapo:code-review` |
-
-`/hapo:debug` is diagnostic-only. Do not edit product code there. Use `/hapo:hotfix` when the user asks to fix.
-
-## Existing System Documentation Workflow
-
-```text
-/hapo:inspect -> /hapo:docs --reconstruct -> human review -> /hapo:specs -> /hapo:develop
-```
-
-| User intent | Suggested start |
-|---|---|
-| understand source structure or locate implementation areas | `/hapo:inspect` |
-| rebuild as-is docs/requirements from a legacy codebase | `/hapo:docs --reconstruct <scope>` |
-| update normal project docs | `/hapo:docs --update` |
-| initialize missing docs | `/hapo:docs --init` |
-| summarize a codebase without full docs work | `/hapo:docs --summarize` |
-
-Do not turn reconstructed docs directly into implementation. Human review must approve the as-is docs before `/hapo:specs` defines future changes.
-
-## Research And Analysis Workflow
+## Core chain
 
 ```text
-/hapo:inspect -> /hapo:research
+/hapo:question -> /hapo:brainstorm -> /hapo:specs -> /hapo:develop -> /hapo:test -> /hapo:code-review -> /hapo:git
 ```
 
-| User intent | Suggested start |
-|---|---|
-| file discovery, codebase structure, source scouting | `/hapo:inspect` |
-| affected files, blast radius, dependency impact, side effects | `/hapo:inspect` |
-| external best practices, tool comparison, technical investigation | `/hapo:research` |
-
-Use `/hapo:research` for external knowledge. Use `/hapo:inspect` for local source truth.
-
-## Delegation Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| assign/offload an implementation task to an external agent CLI (codex, grok) | `/hapo:delegate` |
-
-Claude Code remains the orchestrator: it writes the task brief, dispatches, monitors, and independently verifies the returned work.
-
-## Output Artifact Workflow
-
-| User intent | Suggested skill |
-|---|---|
-| PowerPoint or slide deck creation/editing | `/hapo:pptx` |
-| Word documents | `/hapo:docx` |
-| PDF processing | `/hapo:pdf` |
-| spreadsheets | `/hapo:xlsx` |
-| screenshots, images, audio, video, OCR, multimodal understanding | `/hapo:ai-multimodal` |
+Bug path: `/hapo:debug -> /hapo:hotfix` then test/review. As-is docs: `/hapo:inspect` → `/hapo:docs --reconstruct <scope>` → human review → specs → develop. Delegate implementation to an external agent CLI: `/hapo:delegate`.
 
-## Selection Rules
+## Ambiguous cases
 
-- Pick one primary workflow first.
-- Add a secondary skill only when it materially changes execution.
-- Prefer explicit user commands over this table.
-- If two workflows conflict, ask one concise clarification.
-- If the user asks a factual or project question before workflow selection, use `/hapo:question`.
-- If missing information blocks workflow selection, ask one concise clarification or use `/hapo:brainstorm`.
-- If the user asks to "fix" and root cause is unknown, start with `/hapo:debug` unless the issue is trivial and local.
+| Ambiguity | Prefer | Not when |
+|---|---|---|
+| debug-vs-hotfix | `/hapo:debug` first when root cause unknown | Root cause is known / trivial local fix → `/hapo:hotfix` |
+| question-vs-research | `/hapo:question` to ask about source code, docs, specs, config, dependencies, or project facts | External best-practice comparison / multi-source investigation → `/hapo:research` |
+| question-vs-brainstorm | `/hapo:question` for factual answers with evidence | Vague idea, missing acceptance criteria, unclear scope, multi-approach tradeoffs → `/hapo:brainstorm` |
+| specs-vs-brainstorm | `/hapo:specs` when intent and acceptance are concrete enough | Unclear idea / architecture choices still open → `/hapo:brainstorm` first |

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

@@ -28,4 +28,4 @@ Before returning control to the user or orchestrator, the agent **MUST**:
 
 ### Completion gate (Stop)
 
-Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, an Evidence section (or legacy `Task Test Plan & Verification Evidence` / `Verification & Evidence`) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).
+Marking a task `done` is now machine-gated on the **Stop** hook (`spec-gate.cjs`), not only reminded on each prompt. When a turn ends with *newly-done* tasks, the gate requires a verification receipt in each task markdown: `Status: done`, `## Evidence` (legacy heading aliases still parse) with real proof (no `{{...}}` placeholders; at least one fenced command block or PASS/FAIL line), and a non-empty `task_registry[path].completed_at`. First adoption (no cache yet) seeds history without blocking. Escape hatch for humans: `"spec": { "completion_gate": false }` in `.claude/runtime.json` (missing key keeps the gate ON).

package/src/claude/runtime.json

@@ -13,21 +13,21 @@
   },
   "paths": {
     "docs": "docs",
-    "specs": "specs"
+    "specs": "specs",
+    "plans": "plans"
   },
   "spec": {
     "scaffold_guard": true,
-    "completion_gate": true
+    "completion_gate": true,
+    "tollgate": true
+  },
+  "develop": {
+    "parallel": true
   },
   "locale": {
     "thinkingLanguage": null,
     "responseLanguage": null
   },
-  "skills": {
-    "research": {
-      "useGemini": true
-    }
-  },
   "usage": {
     "enabled": true
   },