@haposoft/cafekit 0.16.0-rc.8 → 0.16.0

package/src/claude/skills/develop/references/subagent-patterns.md

@@ -4,15 +4,18 @@ Load this optional reference only when a task benefits from independent
 inspection, implementation, verification, review, or docs capability. Runtime
 role names are configuration, not workflow policy.
 
-## Dispatch packet
+## Task-local dispatch brief
 
-Every dispatch includes:
+Build the brief from current bytes after loading the plan index once. Include only:
 
-- work context and reports/plans paths;
-- exact task outcome, scope, acceptance, and dependencies;
-- owned read/write paths and explicit exclusions;
-- risk, blast radius, stop conditions, and required evidence;
-- expected status and handoff format.
+- the task's referenced coverage-profile rows;
+- Outcome, Scope, Ownership, Acceptance, Dependencies, and Verification Plan;
+- owned code, its entrypoints/consumers, and explicit exclusions;
+- work context plus reports/plans paths, stop conditions, and handoff format.
+
+Do not forward unrelated plan rows, sibling task bodies, ambient repository
+history, old proof, or a full session transcript. Reread the active task before
+mutation and after sync; a current-byte mismatch returns to the controller.
 
 Use one capability per concrete responsibility. The runtime may map it to an
 available local role, but that mapping cannot add scope or weaken proof.
@@ -26,6 +29,12 @@ available local role, but that mapping cannot add scope or weaken proof.
 - Documentation starts only after a real docs-impact decision.
 - The controller alone writes Status and inline Receipt.
 
+Implementation/worker handoff contains changed paths and owned diff plus, when
+parallel, branch/worktree/Base/Head/complete range and owned-path-tree metadata.
+Verification handoff separately contains the fresh command, exit, named probes,
+counts, output, and observed Head. Neither handoff is itself an inline Receipt;
+only the controller may validate and synchronize it.
+
 A specific-task invocation ends after that task. Full-feature execution may
 continue only after the current task is synchronized and the next dependency
 set is recomputed.
@@ -37,6 +46,11 @@ or run only a permitted main-session check. Never silently substitute an actor
 for an independence requirement. A PENDING, BLOCKED, or provenance-free result
 cannot be normalized to PASS.
 
+After interruption, preserve the owned diff but discard ephemeral handoffs and
+remembered proof. Do not tell an implementation worker to repeat a non-idempotent
+action blindly; scope the resumed brief to unmet Acceptance and require fresh
+verification. Concurrent invocations remain unsupported, so drift blocks handoff.
+
 ## Legacy workflow compatibility
 
 When the selected packet is legacy, include its persisted lane snapshot and

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

@@ -1,5 +1,5 @@
 ---
-name: hapo:docs
+name: cf:docs
 description: "Create, update, summarize, or reconstruct project/system documentation from source code. Use reconstruct mode for as-is documentation of existing or legacy systems with evidence and uncertainty tracking."
 user-invocable: true
 when_to_use: "Invoke to create, update, or reconstruct project documentation from source."
@@ -8,13 +8,13 @@ keywords: [docs, reconstruct, documentation, evidence]
 argument-hint: "[--init|--update|--summarize|--reconstruct] [scope]"
 metadata:
   author: haposoft
-  version: "1.0.0"
+  version: "2.0.0"
 ---
 # Docs
 
 Project documentation workflow for CafeKit.
 
-`hapo:docs` covers two related but distinct jobs:
+`cf:docs` covers two related but distinct jobs:
 
 1. **Normal project docs** — create, update, or summarize living project documentation.
 2. **As-is reconstruction** — rebuild current-state system documentation from source code, especially for existing or legacy systems with missing documents.
@@ -22,11 +22,11 @@ Project documentation workflow for CafeKit.
 ## Command Forms
 
 ```text
-/hapo:docs
-/hapo:docs --init
-/hapo:docs --update
-/hapo:docs --summarize
-/hapo:docs --reconstruct <scope>
+/cf:docs
+/cf:docs --init
+/cf:docs --update
+/cf:docs --summarize
+/cf:docs --reconstruct <scope>
 ```
 
 Mode flags are exclusive. When one is present, use it as the selected mode before interpreting any natural-language scope or instructions.
@@ -42,14 +42,33 @@ Parse the user intent before selecting a mode.
 | Existing docs need refresh after code changes | `update` |
 | Short overview, quick codebase summary, summarize docs | `summarize` |
 
-When `/hapo:docs` has no clear mode:
+When `/cf:docs` has no clear mode:
 
 1. Read the docs root from `.claude/runtime.json`.
-2. If the docs root is missing, choose `init`.
+2. If the docs root is missing, choose `init` (direct invocations only; a post-task checkpoint entry follows the checkpoint contract below instead).
 3. If the docs root exists and user did not request only a summary, choose `update`.
 4. Ask one concise clarification only when choosing between normal docs and as-is reconstruction would change the output materially.
 
-Do not show a menu when prompt intent is already clear.
+Do not show a menu when prompt intent is already clear. Choose the smallest adequate docs work at every entry: narrow broad scopes first and prefer surgical edits over rewrites.
+
+## Post-Task Docs Checkpoint
+
+When Develop or Sync hands off a completed task's docs impact (`none | minor | major`), consume it here. A checkpoint entry never auto-selects `init` and overrides the default mode selection above.
+
+- `none`: report that no docs change is needed and edit nothing.
+- `minor` or `major`: update only affected existing docs, surgically, through the `--update` discipline.
+- A checkpoint never invents a new document and never turns into `--init` without an explicit user request.
+- When `minor`/`major` finds no affected existing doc (including a missing docs root), report the gap and recommend an explicit `/cf:docs --init` or `/cf:docs --update` invocation, creating nothing.
+
+## Delegation Gate
+
+Dispatch subagents (`docs-keeper` writing, parallel doc readers, parallel scouts) only when all three conditions hold:
+
+- The user explicitly requested or permitted delegation or parallel agents.
+- The active runtime exposes an Explore/delegation capability.
+- The work splits into at least two distinct, non-overlapping scopes with useful independent work.
+
+Otherwise continue sequentially in the main agent with the same verification discipline.
 
 ## Output Roots
 
@@ -160,22 +179,22 @@ Load:
 
 ## Reconstruction Is Not Specs
 
-`hapo:docs --reconstruct` MUST NOT:
+`cf:docs --reconstruct` MUST NOT:
 
 - design future behavior
 - add new requirements
 - create implementation tasks
 - create `specs/<feature>/`
-- run `/hapo:develop`
+- run `/cf:develop`
 - claim full business intent from code alone
 
 Correct handoff:
 
 ```text
-/hapo:docs --reconstruct <scope>
+/cf:docs --reconstruct <scope>
 -> human review of as-is docs
--> /hapo:specs <modernization or change request>
--> /hapo:develop <feature>
+-> /cf:specs <modernization or change request>
+-> /cf:develop <feature>
 ```
 
 ## Reconstruction Evidence Rules
@@ -209,9 +228,9 @@ For broad inputs such as `.`, `/`, `whole repo`, or `entire system`:
 Prefer:
 
 ```text
-/hapo:docs --reconstruct apps/admin
-/hapo:docs --reconstruct modules/expense-approval
-/hapo:docs --reconstruct src/features/order
+/cf:docs --reconstruct apps/admin
+/cf:docs --reconstruct modules/expense-approval
+/cf:docs --reconstruct src/features/order
 ```
 
 Avoid reconstructing a large monolith in one pass unless the user explicitly accepts lower precision.
@@ -220,8 +239,8 @@ Avoid reconstructing a large monolith in one pass unless the user explicitly acc
 
 Normal docs workflows reuse the CafeKit docs stack already shipped in the package:
 
-- use `hapo:inspect` or targeted reads to scout source scope
-- use `docs-keeper` for evidence-backed docs writing when delegation is available
+- use `cf:scout` or targeted reads to scout source scope
+- use `docs-keeper` for evidence-backed docs writing only through the Delegation Gate above
 - use `.claude/scripts/validate-docs.cjs <docs-root>` after create/update work
 - use `.claude/scripts/validate-docs-reconstruct.cjs <docs-root>/as-is/<scope-slug>` before a reconstructed bundle is handed to human review
 
@@ -241,7 +260,7 @@ Use these documentation principles:
 
 ## Required Final Report
 
-For any `hapo:docs` run, report:
+For any `cf:docs` run, report:
 
 - files created or updated
 - scope analyzed
@@ -252,7 +271,7 @@ For any `hapo:docs` run, report:
 For `reconstruct`, the recommended next command is usually:
 
 ```text
-/hapo:specs <change request based on approved as-is docs>
+/cf:specs <change request based on approved as-is docs>
 ```
 
 ## References

package/src/claude/skills/docs/references/init-workflow.md

@@ -1,6 +1,6 @@
 # Init Workflow
 
-Use with `/hapo:docs --init`.
+Use with `/cf:docs --init`.
 
 ## Goal
 
@@ -64,7 +64,7 @@ Run a lightweight source scout before deep reading:
    - UI/API/worker/job/deployment surfaces
 4. Split large repositories into scoped source areas.
 
-Use `hapo:inspect` when source discovery spans multiple directories. Prefer targeted reads when the repo is small.
+Use `cf:scout` when source discovery spans multiple directories. Prefer targeted reads when the repo is small.
 
 ### Phase 2: Evidence Scout
 
@@ -84,7 +84,7 @@ Merge scout results into a concise context summary. Keep file references with ea
 
 ### Phase 3: Docs Authoring
 
-Delegate the merged context to `docs-keeper` when available. Otherwise follow its verification discipline in the main context.
+Delegate the merged context to `docs-keeper` only through the Delegation Gate in `../SKILL.md`. Otherwise follow its verification discipline in the main context.
 
 Authoring rules:
 
@@ -126,7 +126,7 @@ Report:
 Recommended next command:
 
 ```text
-/hapo:docs --update
+/cf:docs --update
 ```
 
 after meaningful source changes.

package/src/claude/skills/docs/references/reconstruct-workflow.md

@@ -1,6 +1,6 @@
 # Reconstruct Workflow
 
-Use this reference for `/hapo:docs --reconstruct <scope>`.
+Use this reference for `/cf:docs --reconstruct <scope>`.
 
 ## Goal
 
@@ -11,7 +11,7 @@ This is useful for:
 - existing systems with weak or missing documentation
 - legacy system modernization discovery
 - sales demos showing source-code-to-docs capability
-- preparing a reviewed baseline before `/hapo:specs` creates modernization/change specs
+- preparing a reviewed baseline before `/cf:specs` creates modernization/change specs
 
 ## Non-Goal
 
@@ -87,7 +87,7 @@ Use line numbers when available from reads. If exact line numbers are not availa
 Reconstruction is written for two readers:
 
 1. a domain reviewer who can confirm or reject recovered behavior
-2. a future `hapo:specs` run that needs an approved as-is baseline before change design
+2. a future `cf:specs` run that needs an approved as-is baseline before change design
 
 Write each document so those readers can separate:
 
@@ -144,7 +144,7 @@ Never silently reconstruct a large system as one flat document.
 
 ### 2. Structure And Source Scout
 
-Use `hapo:inspect` patterns or targeted reads to identify:
+Use `cf:scout` patterns or targeted reads to identify:
 
 - project type and language/framework
 - relevant screens/pages/routes
@@ -374,14 +374,14 @@ End with a clear review prompt:
 - answer unknowns
 - add business rules that are not present in code
 
-Do not recommend `/hapo:develop`.
+Do not recommend `/cf:develop`.
 
 Do not call the output approved until human review has resolved high-impact inferred and unknown behavior.
 
 Recommended handoff after review:
 
 ```text
-/hapo:specs <modernization/change request based on approved docs/as-is/<scope-slug>>
+/cf:specs <modernization/change request based on approved docs/as-is/<scope-slug>>
 ```
 
 ## Guardrails

package/src/claude/skills/docs/references/standard-docs-workflow.md

@@ -1,6 +1,6 @@
 # Standard Docs Workflow
 
-Use this shared contract for `/hapo:docs --init`, `/hapo:docs --update`, and `/hapo:docs --summarize`.
+Use this shared contract for `/cf:docs --init`, `/cf:docs --update`, and `/cf:docs --summarize`.
 
 Then load the mode-specific reference:
 
@@ -56,6 +56,10 @@ Create only files that are useful. Minimum viable documentation is preferred ove
 `summarize`:
 - update only `codebase-summary.md`
 
+Post-task checkpoint entry (from Develop/Sync docs impact):
+- `none` reports only; `minor`/`major` update only affected existing docs per the checkpoint contract in `../SKILL.md`
+- a checkpoint never invents a new document and never auto-selects `init`
+
 ### 2. Scout And Verify
 
 Normal docs are current-state living docs. Ground them in:
@@ -66,7 +70,7 @@ Normal docs are current-state living docs. Ground them in:
 - source code that implements the documented behavior
 - tests, CI, deploy config, schemas, migrations, routes when relevant
 
-Use `hapo:inspect` or targeted `rg`/file reads when the project is large. Keep broad scanning scoped by real project areas.
+Use `cf:scout` or targeted `rg`/file reads when the project is large. Keep broad scanning scoped by real project areas.
 
 ### 3. Author Concisely
 

package/src/claude/skills/docs/references/summarize-workflow.md

@@ -1,6 +1,6 @@
 # Summarize Workflow
 
-Use with `/hapo:docs --summarize`.
+Use with `/cf:docs --summarize`.
 
 ## Goal
 
@@ -48,7 +48,7 @@ Read the smallest evidence set needed:
 - runtime entry points and dependency boundaries needed to orient readers
 - tests/config only when they clarify behavior or commands
 
-Use `hapo:inspect` only if the relevant path is unclear. For a broad explicit scan, apply inspect scope gating first.
+Use `cf:scout` only if the relevant path is unclear. For a broad explicit scan, apply scout scope gating first.
 
 ### Phase 3: Write Summary
 

package/src/claude/skills/docs/references/update-workflow.md

@@ -1,6 +1,6 @@
 # Update Workflow
 
-Use with `/hapo:docs --update`.
+Use with `/cf:docs --update`.
 
 ## Goal
 
@@ -20,7 +20,7 @@ Refresh existing living docs after code or project-state changes without rewriti
 
 1. Read repo instructions and docs root.
 2. Verify the docs root exists.
-3. If the docs root does not exist, switch to `init` or explain that no docs baseline exists.
+3. If the docs root does not exist, switch to `init` or explain that no docs baseline exists. A post-task checkpoint entry never switches to `init`; it reports the gap and recommends an explicit `/cf:docs --init` invocation instead.
 4. Identify update focus:
    - user-named module or doc
    - recent source diff
@@ -39,7 +39,7 @@ Scout source areas that can affect docs:
    - design/code standards
    - roadmap/changelog state
 3. Run targeted source reads for evidence.
-4. Use `hapo:inspect` only when the affected scope is unclear or broad.
+4. Use `cf:scout` only when the affected scope is unclear or broad.
 
 Do not treat commit messages as sufficient evidence. Verify changed behavior in code, tests, config, or schemas.
 
@@ -52,8 +52,10 @@ Use document count and file size to decide reading strategy:
 | Docs set | Reading strategy |
 |---|---|
 | 1-3 markdown files | Read directly |
-| 4-6 markdown files | Split across 2-3 readers when delegation is available |
-| 7+ markdown files | Split across up to 5 readers by LOC and topic |
+| 4-6 markdown files | Split across 2-3 readers only when the Delegation Gate in `../SKILL.md` is open |
+| 7+ markdown files | Split across up to 5 readers by LOC and topic through the same open gate |
+
+When the gate is closed, read the set sequentially in the main agent.
 
 Each reading pass extracts:
 
@@ -67,7 +69,7 @@ Merge source scout and docs readings before writing.
 
 ### Phase 2: Surgical Docs Update
 
-Delegate to `docs-keeper` when available. The update must stay surgical:
+Delegate to `docs-keeper` only through the Delegation Gate in `../SKILL.md`; when the gate is closed, apply the same discipline in the main agent. The update must stay surgical:
 
 1. Edit only affected docs and sections.
 2. Remove or rewrite stale claims when source evidence contradicts docs.
@@ -119,5 +121,5 @@ Report:
 If a requested change belongs to future behavior rather than current project docs, recommend:
 
 ```text
-/hapo:specs <change request>
+/cf:specs <change request>
 ```

package/src/claude/skills/docs/templates/requirements-as-is.md

@@ -31,4 +31,4 @@ Each requirement records current behavior only.
 ## Open Review Notes
 
 - Replace template examples with source-backed requirements.
-- Move requested future changes to `/hapo:specs`, not this file.
+- Move requested future changes to `/cf:specs`, not this file.

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

@@ -1,5 +1,5 @@
 ---
-name: hapo:docx
+name: cf:docx
 description: Create, edit, analyze .docx Word documents. Use for document creation, tracked changes, comments, formatting preservation, text extraction, template modification.
 license: Proprietary. LICENSE.txt has complete terms
 user-invocable: true

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

@@ -1,5 +1,5 @@
 ---
-name: hapo:git
+name: cf:git
 description: "Hapo Native Git Operations & Worktree Management. Handles safe commits, conventional split, branch finish choices, secret scanning, and sibling-branch worktrees locally."
 user-invocable: true
 when_to_use: "Invoke for commits, PRs, branch hygiene, or worktree management."

package/src/claude/skills/git/references/commit-protocols.md

@@ -36,4 +36,4 @@ git add -A && git diff --cached --stat && git diff --cached --name-only
 ## Xử lý Vướng Mắc Git (Error Handling via Bash)
 - **Có Secret bị rò rỉ:** Cảnh báo đỏ. Gọi lệnh xoá file đó khỏi staged `git rm --cached <file>`. Cảnh cáo người dùng.
 - **Push bị báo Rejected:** Cấm dùng `--force` mù quáng. Yêu cầu chạy Bash: `git pull --rebase origin <branch>`.
-- **Merge Conflicts:** Báo "BLOCKED", in lệnh Bash hướng dẫn người dùng chạy command giải quyết hoặc gọi agent `hapo:develop` xử lý conflict file.
+- **Merge Conflicts:** Báo "BLOCKED", in lệnh Bash hướng dẫn người dùng chạy command giải quyết hoặc gọi agent `cf:develop` xử lý conflict file.

package/src/claude/skills/git/references/finish-branch.md

@@ -1,6 +1,6 @@
 # Finish Branch Protocol
 
-Use this protocol for `hapo:git finish`.
+Use this protocol for `cf:git finish`.
 
 ## Goal