@haposoft/cafekit 0.16.7 → 0.18.1

package/src/claude/skills/develop/references/parallel-waves.md

@@ -70,11 +70,3 @@ After the final wave, run feature integration and reachability proof. The contro
 then writes inline Receipts and Status one task at a time. Worker reports and range
 metadata are inputs, not completion authority; incomplete workers cannot be hidden
 by successful siblings.
-
-## Legacy workflow compatibility
-
-For an existing `spec.json` feature, readiness and dependencies come from the
-persisted `task_registry` and typed `coordination.boundaries`. Workers still do
-not edit that state. The controller writes the legacy separate task receipt,
-synchronizes registry plus nested task Markdown, and creates the required final
-feature receipt only after integrated proof.

package/src/claude/skills/develop/references/quality-gate.md

@@ -26,7 +26,10 @@ Before completion, verify:
 4. negative/failure behavior named by Acceptance;
 5. artifact bytes and SHA-256 when the task declares an artifact;
 6. an inline `## Receipt` with `Verification: PASS`, exact `Command`, `Exit: 0`,
-   runtime-bound Base/Head, and non-empty fenced command output;
+   runtime-bound Base/Head, and non-empty fenced command output; take Base and Head
+   from the `Base` and `Head` fields printed by
+   `node .claude/scripts/provenance.cjs --project-root . --specs-root specs --spec-file <task file> --feature-name <feature> --session <any label> --json`,
+   run after the last change outside the specs root, and never type, abbreviate, or compute them by hand;
 7. correctness/security/scope review at the required depth.
 
 `PRECHECK_FAIL` outranks no-tests. Missing, pending, placeholder, contradictory,
@@ -74,19 +77,25 @@ manufacture a green result.
 
 ## Final-Head fixed point
 
-Before C3, repeat within the same three-round repair cap:
+Before GATE-DONE, repeat within the same three-round repair cap:
 
 1. Capture runtime Head and list every `done` task whose Receipt is stale or
    bound to a different Head.
 2. Run each stale task's exact proof freshly and let only the controller replace
-   its inline Receipt. If proof changes any non-Specs byte, stop as BLOCKED;
+   its inline Receipt. A Receipt that declares artifacts with `sha256` may instead be
+   rebound to the current Head once every declared hash is recomputed and matches, and only
+   when no file the proof reads changed between its recorded Head and the current one and
+   every claim in the Receipt is derived from those artifacts; matching bytes prove the
+   artifacts did not move, not that the proof would still produce them. Otherwise, and for a
+   Receipt with no artifact, re-run; only the controller rebinds.
+   If proof changes any non-Specs byte, stop as BLOCKED;
    remediation must settle those bytes before proof can bind them.
 3. Capture runtime Head again and rescan all `done` Receipts.
 
 Stop only when consecutive Head captures are identical and every `done` Receipt
 names that current Head. A single pass, remembered result, copied Receipt, or
 proof promoted from another level is not a fixed point. If Head keeps moving or
-the repair cap is reached, report the blocker instead of opening C3.
+the repair cap is reached, report the blocker instead of opening GATE-DONE.
 
 ## Flash gate
 
@@ -106,16 +115,9 @@ report production readiness. Only a later explicit non-Flash invocation may
 recover it: discard Flash output as canonical evidence, inspect current bytes
 and the owned diff, and run fresh proof under the same sync-finalize contract.
 
-## Docs impact and C3
+## Docs impact and GATE-DONE
 
 After proof and review, classify docs impact as `none`, `minor`, or `major`.
 Update only affected existing docs when impact is not none. Show the user the
-current command evidence and limitations at C3; do not infer approval from a
+current command evidence and limitations at GATE-DONE; do not infer approval from a
 receipt.
-
-## Legacy workflow compatibility
-
-Existing kernel packets keep their separate `receipts/<task-basename>.md`, task
-identity/path metadata, final `feature-receipt.md`, persisted independent-audit
-obligations, and completion-authority checks. The same proof/review ownership
-applies. Do not copy that storage shape into a flat process-first task.

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

@@ -50,9 +50,3 @@ 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
-obligations in the dispatch, but do not let workers edit that state or infer an
-independent result from a role label.

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

@@ -125,7 +125,7 @@ Create the standard project docs set from the current source code.
 Use when:
 - the repository has code but no useful docs
 - the user asks to create project docs
-- SessionStart docs-sync reports missing documentation
+- `echo '{}' | node .claude/hooks/docs-sync.cjs` reports missing documentation
 
 Load:
 - `references/standard-docs-workflow.md`
@@ -138,7 +138,7 @@ Refresh existing docs after code changes.
 Use when:
 - docs exist and source code changed
 - the user asks to update or refresh docs
-- docs-sync reports stale docs
+- `echo '{}' | node .claude/hooks/docs-sync.cjs` reports stale docs
 
 Load:
 - `references/standard-docs-workflow.md`

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

@@ -24,7 +24,7 @@ Refresh existing living docs after code or project-state changes without rewriti
 4. Identify update focus:
    - user-named module or doc
    - recent source diff
-   - docs-sync stale hash signal
+   - docs-sync stale hash signal (run `echo '{}' | node .claude/hooks/docs-sync.cjs` from the project root)
    - a full docs refresh only when user asks for it
 
 ### Phase 1: Source Change Scout

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

@@ -0,0 +1,153 @@
+---
+name: cf:fix
+description: "Use when asked to FIX a bug, error, test failure, CI/CD issue, type error, lint error, log error, UI issue, or code problem. Uses cf:debug for evidence-first diagnosis before any code change."
+user-invocable: true
+when_to_use: "Invoke to fix a bug or failure with scout-first diagnosis before change."
+category: dev-tools
+keywords: [hotfix, fix, bug, diagnosis]
+argument-hint: "[issue] --quick|--parallel|--from-debug"
+metadata:
+  author: haposoft
+  version: "2.0.0"
+---
+# Fix — root-cause repair workflow
+
+Fix the diagnosed root cause, prove the fix with fresh evidence, and leave no side effects. Evidence first, fix second.
+
+## Arguments
+
+- `--quick` - Reduced-depth path for trivial issues (lint, type errors, syntax); still scout-first
+- `--parallel` - Fix independent issues concurrently, only through the Delegation Gate below
+- `--from-debug` - Start from an existing `cf:debug` report and validate its contract before accepting it
+
+Default: deterministic scout-first fix. There is no initial mode selection step.
+
+## Proportional depth
+
+Choose the smallest adequate depth from the diagnosed evidence. Depth vocabulary follows `cf:debug`:
+
+- **Quick/local:** one deterministic syntax, lint, type, or isolated-test failure with obvious local scope. Quick mode only reduces depth; it never skips scout, pre-fix evidence, diagnosis, or before/after verification.
+- **Standard:** a diagnosed root cause inside one bounded area. Fix plus a regression test seen failing on the unchanged code before the fix (`HARD-GATE-RED-BEFORE-FIX`) and passing after it.
+- **Incident/deep:** production impact, multiple components, intermittent behavior, data/security risk, or concurrency. Consume the full Incident/deep debug handoff (timeline, elimination path, recurrence candidates), implement in stages, and verify each stage.
+
+Depth changes evidence breadth, never the gates: scout, diagnosis, before/after proof, and the side-effect gate apply at every depth.
+
+## Bounded repair frame
+
+Quick/local does not add a separate framing ceremony when the issue and diagnosis already establish the repaired behavior and proof. For Standard or Incident/deep, or whenever scope or risk remains ambiguous after diagnosis, record four short fields before choosing an implementation:
+
+- **Outcome:** the observable repaired behavior.
+- **Constraints:** compatibility, safety, ownership, rollout, and time boundaries.
+- **Non-goals:** adjacent behavior the repair must not absorb.
+- **Acceptance:** the exact reproduction plus broader evidence that proves completion.
+
+Derive repository-owned facts from scout and diagnosis. Ask the user only for a missing user-owned decision that could materially change the repair. This frame does not select a solution, widen the issue into feature work, or run before the root cause is proven.
+
+<HARD-GATE>
+Do not propose or implement a fix before scout and diagnosis complete.
+A symptom patch without a diagnosed root cause is a failed fix.
+The exact root-cause contract under Diagnosis is mandatory; answer each field in one concrete sentence.
+An answer containing 'probably', 'I think', 'something with', or 'maybe' is not an answer; gather evidence instead.
+If 3+ fix attempts fail, stop, question the architecture, and discuss with the user.
+</HARD-GATE>
+
+<HARD-GATE-SCOUT-FIRST>
+Fix always scouts before asking broad clarification questions, forming hypotheses, or changing files.
+Collect these scout outputs first: the project type, language(s), framework(s), and package/test runner from repo files; the exact file(s) where the symptom surfaces and their direct callers/dependents; related tests covering the affected area; recent commits touching affected files (`git log --oneline -10 -- <affected-files>`); and existing patterns/conventions for this kind of fix.
+Then state a concise 3-6 bullet codebase-context summary before diagnosis.
+Do not ask generic questions before this step unless there is no repo, no error text, and no observable artifact to inspect.
+</HARD-GATE-SCOUT-FIRST>
+
+<HARD-GATE-RED-BEFORE-FIX>
+Before the first change to any non-test file (an edit, a file write, or a shell command that rewrites it), run a test that fails on the unchanged code for the diagnosed reason, and keep its exact command and failing output for verification.
+For a lint, type, syntax, or build failure, the exact failing check run on the unchanged code stands in for the test.
+When no existing test fails for that reason, write or update the regression test first, then run it and see it fail.
+Red shown after the fact does not count: stashing, checking out, reverting, or editing the fix away to make the test fail is not pre-fix evidence.
+If no automated test or check can reproduce the failure, say so and keep the exact manual reproduction and its observed output instead.
+This applies at every depth.
+</HARD-GATE-RED-BEFORE-FIX>
+
+<HARD-GATE-NO-SIDE-EFFECTS>
+The fix is not done until verification proves:
+1. The original symptom no longer reproduces with the exact pre-fix command/user flow.
+2. Modified files and transitively affected modules still pass relevant tests.
+3. Blast-radius workflows have no business-logic regression.
+4. No new lint/type/build errors were introduced.
+5. Public contracts are unchanged unless intentionally called out: function signatures, exported types, response shapes, DB schemas, env vars.
+
+If verification reveals a side effect or regression, stop and present 2-4 concrete options to the user:
+- Revert this fix and try a different root-cause angle
+- Keep the fix and update <dependent files> to match the new contract
+- Narrow the fix to <subset> so the regression disappears
+- Accept the change — the old behavior was itself a bug
+Do not silently patch around the regression.
+</HARD-GATE-NO-SIDE-EFFECTS>
+
+## Delegation Gate
+
+Dispatch subagents (parallel scouts, hypothesis tests, deep research, or
+`--parallel` fix trees) 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 focused local evidence.
+Task-tracking tools are an optional visibility fallback, never a required step;
+a concise markdown checklist is always sufficient.
+
+## Standards
+
+**Scout.** Map the blast radius before any hypothesis, with `cf:scout` or an equivalent focused local scout (`rg` plus targeted reads); scout depth follows the depth: Quick/local maps the project type, affected file(s), direct callers/dependents, related tests, and recent commits; Standard and deeper add module boundaries, test coverage, call chains, recent changes, and existing patterns; `--parallel` runs one independent scout per issue, only through the Delegation Gate.
+
+**Diagnosis.** Evidence-based root cause analysis; no guessing. `cf:debug` may help and `--from-debug` validates its report, but neither is a required call; `references/diagnosis-protocol.md` holds the Fix-local checklist. Capture the pre-fix state first: exact error messages, failing test output, stack traces; this is the baseline for verification. When an existing test already fails for the diagnosed reason, its run belongs to this baseline; otherwise the regression test is written and seen failing at the start of implementation under `HARD-GATE-RED-BEFORE-FIX`. Locate where and when the failure started (`git log -p`), form 2-3 hypotheses each with confirm/refute evidence and a quick test, test them with focused local reads (in parallel only through the Delegation Gate), and trace symptom → immediate cause → contributing factor → root cause. If 2+ hypotheses fail, apply `references/escalation-tactics.md`.
+
+**Exact root-cause contract** (field definitions in `references/diagnosis-protocol.md`; Expected and Actual may be one field): Symptom, Reproduction, Expected vs actual, Trigger, Root cause (file:line, config, environment, dependency, or data source), Contributing factors, Why now, Evidence chain, Blast radius.
+- Trigger: event or input that activated the failure, or `unknown`
+- Contributing factors: conditions that raised likelihood or impact but are not sufficient causes, or `none evidenced`
+
+With `--from-debug`, validate the report before accepting it:
+
+- the exact root-cause contract is complete;
+- when `**Depth:**` is `incident/deep`, `Evidence Timeline` is present — a skipped timeline is valid in either producer form (`Timeline: skipped - <reason>` or `- skipped: <reason>`), as is one line naming the sources checked when none carries timestamps;
+- when `**Depth:**` is `incident/deep`, `Elimination Path` records the decisive observation for each removed or retained candidate;
+- a `quick/local` or `standard` report may omit both; a report with no `**Depth:**` line is treated as `incident/deep`;
+- `Recurrence-Prevention Handoff`, when present, carries evidence-backed candidates only.
+
+A report missing required fields routes back to diagnosis (`cf:debug`); it does not enter implementation.
+
+If any contract field is vague or missing file:line/config/env evidence, keep diagnosing or ask the user for the specific missing artifact. Do not implement.
+
+**Depth and frame.** Apply the Proportional depth rule above. For 2+ independent issues (or `--parallel`), evaluate the Delegation Gate; when it is closed, fix the issues sequentially. Track progress with the runtime's task surface when available, or a markdown checklist otherwise. For Standard and Incident/deep, complete the bounded repair frame above. Quick records no separate frame unless scope or risk is still ambiguous.
+
+**Implementation.** Fix the root cause, not the symptom. Follow diagnosis findings. Minimal changes only; follow existing code patterns. One logical change per commit boundary.
+- **Quick:** with the pre-fix failure observed under `HARD-GATE-RED-BEFORE-FIX`, apply the minimal fix from completed scout + diagnosis, run the exact pre-fix command plus typecheck/lint immediately, report before/after proof.
+- **Standard:** write or update the regression test and run it to see it fail on the unchanged code (`HARD-GATE-RED-BEFORE-FIX`), then implement the fix, rerun the same test to see it pass, and run the relevant suite.
+- **Incident/deep:** after diagnosis, research only unresolved external facts. If multiple cause-aligned remedies or an architecture decision remain, use `cf:brainstorm` to compare 2-3 options against the bounded repair frame, then write a concise staged implementation plan with dependencies and proof per stage. When diagnosis leaves one safe direct repair, skip research and brainstorm, record why it satisfies the frame, and implement it. Delegated research follows the Delegation Gate; implementation starts only after the direction is resolved.
+- **Parallel:** one independent issue per agent, each carrying scout through verification, dispatched only through the Delegation Gate; aggregate results on completion.
+
+**Verification and prevention.** Iron-law verification: run the exact commands from the pre-fix state capture and compare output. No claims without fresh command output from the current run. The regression proof is the failing run kept under `HARD-GATE-RED-BEFORE-FIX` and a passing run of the same test after the fix. Full check: typecheck + lint + build + test (see `references/parallel-patterns.md` Pattern C). Prevention guard (Standard+): see `references/prevention-gate.md`; consume the debug report's recurrence candidates when present. Side-effect gate: sweep the full blast radius from diagnosis against the five checks in the gate above. Review: trigger `cf:code-review`; see `references/review-cycle.md`.
+
+Verification and review report `PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`. The definition of `PASS` defers to `cf:code-review`. `PASS_WITH_WARNINGS` routes through the same remediation or user-pause path as `FAIL` and never auto-accepts. `BLOCKED` is terminal for the cycle; resolve the blocker instead of retrying. A review-only result is not execution proof; completion claims require fresh command output.
+
+If verification fails: under 3 attempts, return to diagnosis with the new evidence; at 3+ attempts, stop and discuss with the user. Never weaken, delete, or mock a failing assertion to obtain green.
+
+**Finalize.** If API or behavior changed, update only the affected existing docs through the docs flow. Ask the user before committing; use conventional commits.
+
+## Output Format
+
+**Report:** root cause, changes made, files affected, before/after proof, prevention measures, side-effect sweep result, and any remaining limitations.
+
+## Specialized Paths
+
+Use `references/workflow-specialized.md` as a progressively disclosed overlay after scout for CI/CD failures, test suite failures, TypeScript type errors, UI/visual issues, and application log errors. Load only the matching section. Specialized paths add category-specific evidence and proof; they do not replace these standards, weaken diagnosis, or broaden the repair scope.
+
+## References
+
+Load as needed:
+- `references/diagnosis-protocol.md` — Structured root cause analysis and the exact root-cause contract
+- `references/escalation-tactics.md` — What to do when hypotheses fail (Inversion, Scale Game)
+- `references/prevention-gate.md` — Defense-in-depth validation after fix
+- `references/review-cycle.md` — Review verdict handling and required user-pause conditions
+- `references/parallel-patterns.md` — Delegation Gate patterns for parallel work
+- `references/workflow-specialized.md` — CI/CD, test, TypeScript, UI-specific workflows

package/src/claude/skills/{hotfix → fix}/references/diagnosis-protocol.md

@@ -20,7 +20,7 @@ Before any investigation, capture the current broken state as baseline:
 5. Record git status / recent changes: git log --oneline -10
 ```
 
-This baseline is required for Step 5 (Verify) — you MUST compare before/after.
+This baseline is required for verification — you MUST compare before/after.
 
 ## Diagnosis Chain (Follow in Order)
 
@@ -86,7 +86,7 @@ Symptom (where error appears)
 
 ## Exact Root-Cause Contract
 
-Before Step 4 implementation in `cf:fix`, record:
+Before implementation in `cf:fix`, record:
 
 - Symptom: exact observable failure
 - Reproduction: command, user flow, CI job, log trigger, or route

package/src/claude/skills/{hotfix → fix}/references/parallel-patterns.md

@@ -38,7 +38,7 @@ Wait for all agents to return. Merge their findings into a unified context map b
 
 ## Pattern B: Parallel Hypothesis Verification
 
-After forming 2-3 hypotheses in Step 2 (Diagnose), test them concurrently:
+After forming 2-3 hypotheses during diagnosis, test them concurrently:
 
 ```
 Agent(subagent_type="Explore", prompt="Verify hypothesis: cache returns stale data — check TTL config in src/cache/")
@@ -98,7 +98,7 @@ Agent(subagent_type="Explore", prompt="Scout scope B: map runtime/config paths a
 ```
 
 Wait for the scout evidence, synthesize the required codebase-context summary,
-then begin hypotheses and diagnosis. Research begins only after Step 2 diagnosis
+then begin hypotheses and diagnosis. Research begins only after diagnosis
 proves the root cause and identifies one unresolved external fact. It may inform
 a post-diagnosis remedy decision; it never substitutes for repository evidence
 or selects a fix early.

package/src/claude/skills/{hotfix → fix}/references/prevention-gate.md

@@ -1,6 +1,6 @@
 # Prevention Gate
 
-After a fix is verified, apply defense-in-depth to prevent the same bug class from recurring. Prevention is not the same as side-effect safety; run the Step 5 side-effect sweep in `../SKILL.md` before claiming completion.
+After a fix is verified, apply defense-in-depth to prevent the same bug class from recurring. Prevention is not the same as side-effect safety; run the side-effect sweep in `../SKILL.md` before claiming completion.
 
 When the debug report carries a `Recurrence-Prevention Handoff`, consume its
 evidence-backed candidates (missing invariant or validation layer,
@@ -12,8 +12,8 @@ of inventing new ones.
 For every fix (Standard+ complexity), evaluate and apply at least ONE:
 
 ### 1. Regression Test Guard
-- Write a test that specifically covers the fixed issue
-- The test MUST fail without the fix and pass with it
+- A test that specifically covers the fixed issue and was seen failing on the unchanged code before the fix (`HARD-GATE-RED-BEFORE-FIX` in `../SKILL.md`) counts as this guard
+- Red produced afterwards by undoing the fix does not count; the test MUST pass with the fix
 - Place it near related existing tests for discoverability
 
 ### 2. Input Validation Guard

package/src/claude/skills/{hotfix → fix}/references/review-cycle.md

@@ -14,7 +14,7 @@ LOOP:
   2. Evaluate:
      IF verdict == PASS:
        → ACCEPT. Log: "✓ Review PASS"
-       → Proceed to Step 6 (Finalize)
+       → Proceed to Finalize
 
      ELSE IF verdict == BLOCKED:
        → TERMINAL STOP. Do not blind-retry.

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

@@ -18,21 +18,58 @@ Git operations and worktree management using plain `git` commands.
 Present options via AskUserQuestion — header "Git Operation": commit / push / pr / finish / worktree.
 
 ## Commands
-- `commit`: run installed secret scanner → analyze diff → split into conventional commits.
+- `commit`: confirm the target checkout before staging → scan the working tree for secrets before anything is staged → analyze the diff → stage and commit by group (`references/commit-protocols.md`).
 - `push`: push current branch.
 - `pr`: push + open PR. Target = repo's integration branch — detect via
   `gh repo view --json defaultBranchRef` or `origin/HEAD`; never assume `main`/`develop`.
 - `finish`: fresh `git status` + verification, then present exactly 4 options:
-  merge locally / push + PR / keep branch-worktree / discard (typed confirmation).
-- `worktree <desc>`: sibling dir `../<project>-<branch>` for isolated setup.
+  merge locally / push + PR / keep branch-worktree / discard (typed confirmation, as in the worktree lifecycle: `remove <dir-name>` / `delete <branch>`).
+- `worktree <desc>`: sibling dir `../<project>-<branch>` for isolated setup, branched from the current branch unless the user names a base, hydrating the installer-ignored `.claude/`, `.codex/`, `.agents/` it lacks. Git alone is enough (plus `rsync`); Orca, Herdr and Claude Code's own worktree are optional shortcuts, never required.
+- `worktree list | remove <dir> | prune`: lifecycle in `references/worktree-blueprint.md` — never lose uncommitted, ignored or unmerged work: before `git worktree remove`, check `git -C <dir> status --porcelain --ignored` and `git -C <dir> log --oneline <base>..HEAD`, never `--force`, and anything they show needs the typed `remove <dir-name>`; use `git worktree prune` for a missing directory, never `rm -rf`.
 
-## Secret scan (before every commit)
+## Hard rules for `commit`
+- Stage by explicit paths, group by group; never `git add -A`, `git add .`, `git add -u` or `git commit -a` (`-am` included).
+- Confirm the target checkout before staging: print `git rev-parse --show-toplevel` and `git branch --show-current` of the directory you will commit in, check they match what the user asked for, then run every stage and commit with `git -C <target>` (or after a `cd <target>`).
+- Commit messages carry no `Co-Authored-By` and no other AI attribution trailer, unless the user asked for one in this request — even where a host's default guidance suggests it.
+- Push only the current branch, never with `--force`. Bash on macOS is 3.2: no `mapfile`, `readarray`, `declare -A`, `${var,,}`, `${var^^}`, `&>>`.
+
+## Secret scan (before anything is staged)
+Scan the working tree first, so a secret never reaches the index. Run this working-tree scan before staging whether or not the helper is installed, inside the target checkout (`cd <target>` first; the block moves to the repository's top-level itself). Do not print file contents or diffs of changed files before the scan has run: look at `git status --short` and `git diff --stat` only, and never `cat`, `git diff`, `git show` or Read a file the scan flagged.
+
+The block is bash 3.2 and BSD awk safe. It reads the added lines of tracked changes (or the staged diff when the repository has no commit yet) plus every untracked file, and prints `file:line:class` and nothing else: never the line, a value, or context. Prose such as the word `tokens` and empty or env-referencing values do not match.
+
+<!-- fallback-scan:start -->
 ```bash
-node .claude/scripts/scan-staged-secrets.cjs
+cd "$(git rev-parse --show-toplevel)" || exit 1
+D='-c core.quotePath=false diff -U0 --no-color --no-ext-diff --src-prefix=a/ --dst-prefix=b/'
+{ git $D HEAD 2>/dev/null || git $D --cached
+  git -c core.quotePath=false ls-files -z --others --exclude-standard | while IFS= read -r -d '' f; do
+    printf '+++ b/%s\n@@ -0,0 +1 @@\n' "$f"; sed 's/^/+/' "$f"; echo; done
+} | tr -d '\r' | awk '
+function val(l,   n, lo, r, q, v, i, w) {
+  n = l; gsub(sprintf("%c", 39), "\"", n); gsub(sprintf("%c", 96), "\"", n); lo = tolower(n)
+  if (!match(lo, /(api[_-]?key|secret|password|passwd|token|private[_-]?key)[a-z0-9_-]*["]?[ ]*[:=][ ]*/)) return 0
+  r = substr(n, RSTART + RLENGTH); q = substr(r, 1, 1)
+  if (q == "\"") { r = substr(r, 2); i = index(r, "\""); if (i == 0) return 0; v = substr(r, 1, i - 1)
+    return (length(v) >= 12 && v !~ /^[$<]/ && v !~ /^process[.]env/) }
+  split(r, w, " "); v = w[1]
+  return (v ~ /^[A-Za-z0-9+\/_=-]+$/ && length(v) >= 16)
+}
+/^[+][+][+] /  { f = ($(0) ~ /^[+][+][+] b\//) ? substr($(0), 7) : ""; sub(/\t.*$/, "", f); next }
+/^@@/          { split($(3), a, ","); n = substr(a[1], 2) - 1; next }
+/^[+]/         { n++; if (f == "") next; l = substr($(0), 2); c = ""
+  if (val(l)) c = "assignment"
+  if (match(l, /sk-[A-Za-z0-9_-]+/) && RLENGTH >= 20) c = "sk-prefix"
+  if (match(l, /gh[pousr]_[A-Za-z0-9]+/) && RLENGTH >= 20) c = "gh-prefix"
+  if (match(l, /Bearer [A-Za-z0-9._-]+/) && RLENGTH >= 27) c = "bearer"
+  if (l ~ /-----BEGIN [A-Z ]*PRIVATE KEY-----/) c = "private-key-block"
+  if (c != "") print f ":" n ":" c }'
 ```
-The helper parses `git diff --cached --unified=0 --no-color --diff-filter=ACMR`, checks added lines only, maps hunks to source lines, and prints only file, line, and identifier. It never prints secret values or context.
+<!-- fallback-scan:end -->
 
-Match → STOP. For an untracked secret, add an appropriate `.gitignore` rule. For a tracked secret, stop, rotate it, and ask the user before changing history or index state.
+With the helper installed (`.claude/scripts/scan-staged-secrets.cjs`), also run `node .claude/scripts/scan-staged-secrets.cjs` after staging, as a second look at the staged diff (it parses `git diff --cached --unified=0 --no-color --diff-filter=ACMR`, checks added lines only, and prints only file, line, and identifier).
+
+Match → STOP everything: commit nothing, not even the clean groups. Report file, line and class only. Do not run `git reset`, `git restore --staged` or `git rm --cached`, and do not edit `.gitignore` or history, before the user answers; with the helper, say which files are already staged. Then let the user choose: for an untracked secret a `.gitignore` rule, for a tracked one rotating it first.
 
 ## Split rules
 Split when: mixed types (feat+fix), mixed scopes, config/deps mixed with code, >10 unrelated files.
@@ -40,8 +77,9 @@ Single commit when: same type+scope, ≤3 files, ≤50 lines.
 
 ## Output
 ```
-✓ staged: N files (+X/-Y)
+✓ checkout: <top-level> @ <branch>
 ✓ secrets: none
+✓ staged: N files (+X/-Y)
 ✓ commit: <hash> type(scope): description
 ✓ pushed: yes|no
 ```
@@ -49,7 +87,8 @@ Single commit when: same type+scope, ≤3 files, ≤50 lines.
 ## Errors
 | Error | Action |
 |---|---|
-| Secrets matched | Block; report only file/source line/identifier. Never show secret value, diff line, or surrounding context. |
+| Secrets matched | Stop all commits; report only file/source line/class. Never show secret value, diff line, or surrounding context. |
+| Wrong checkout or branch | Stop before staging; say what differs and ask |
 | Nothing staged | Exit cleanly |
 | Push rejected | Suggest `git pull --rebase` |
 | Conflicts | List files; never auto-resolve |

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

@@ -1,31 +1,48 @@
 # Định Dạng & Tiêu Chuẩn Commit (Hapo Git Protocols)
 
-Bộ quy chuẩn Native dành cho Hapo Agents khi gọi lệnh `commit`. Không dùng tool bên ngoài, LLM phải tự phân tích qua Bash.
+Bộ quy chuẩn Native dành cho Hapo Agents khi gọi lệnh `commit`. Không dùng tool bên ngoài, LLM phải tự phân tích qua Bash. Các bước dưới đây theo đúng thứ tự: kiểm checkout → quét bí mật → stage theo nhóm → commit.
 
-## Chuẩn Bị (Staging Setup)
-Khởi động bằng lệnh Bash:
+## Bước 0 — Xác nhận đúng checkout TRƯỚC khi stage
+Xác định thư mục đích (người dùng nêu, hoặc thư mục hiện tại). In top-level và nhánh của CHÍNH thư mục đó:
 ```bash
-git add -A && git diff --cached --stat && git diff --cached --name-only
+git -C <đích> rev-parse --show-toplevel
+git -C <đích> branch --show-current
 ```
+Chỉ đi tiếp khi cả hai khớp thứ người dùng nhắm tới. Từ đây mọi lệnh stage và commit chạy bằng `git -C <đích>` (hoặc sau một `cd <đích>`; thư mục làm việc được giữ giữa các lệnh). Không khớp (đứng nhầm repo, sai nhánh, detached HEAD) thì dừng trước khi stage, nói rõ lệch ở đâu và hỏi người dùng.
+
+Bash trên macOS là bash 3.2: không dùng `mapfile`, `readarray`, `declare -A`, `${var,,}`, `${var^^}`, `&>>`; dùng vòng `while read` hoặc `$(...)` thay thế.
+
+## Bước 1 — Quét bí mật khi CHƯA stage
+Chỉ xem `git status --short` và `git diff --stat` trước khi quét; không in nội dung hay diff của file đã đổi (`cat`, `git diff`, `git show`) khi chưa quét xong. Luôn chạy khối quét cây làm việc trong `SKILL.md` (giữa hai dấu `fallback-scan`) TRƯỚC khi stage, dù repo có script quét hay không, và chạy nó bên trong checkout đích (`cd <đích>` trước). Nếu repo có script, chạy thêm nó SAU khi stage như một lần nhìn thứ hai vào diff đã stage. Kết quả chỉ gồm file, dòng, loại — không bao giờ in giá trị.
+
+Có trúng → dừng TOÀN BỘ, không commit gì, kể cả các nhóm sạch. Không đổi index hay `.gitignore` trước khi người dùng trả lời; quy tắc đầy đủ nằm ở `SKILL.md`.
+
+## Bước 2 — Stage theo nhóm bằng đường dẫn tường minh
+Đọc `git status --short` và `git diff --stat` rồi quyết định chia commit. Mỗi nhóm stage riêng, ví dụ:
+```bash
+git -C <đích> add -- src/a.js src/b.js
+git -C <đích> diff --cached --stat
+```
+Không có gì được stage → thoát gọn.
 
 ## Giải Thuật: Tách Commit (Auto-Split vs Single Commit)
 
-Đọc kỹ Data do `git diff --cached --stat` cung cấp để ra quyết định chia nhỏ Commit bằng lệnh `git reset HEAD <file>` và `git add <file>`.
+Đọc kỹ dữ liệu do `git diff --cached --stat` cung cấp để quyết định chia nhỏ commit.
 
-**Tiến hành NGAY LẬP TỨC việc Tách (Split) Commit NẾU:**
-1. Có sự khác nhau rõ ràng về Loại Hành Động (Types): Có cả `feat` (tính năng) và `fix` (sửa lỗi) trong cùng 1 cục rổ.
-2. Có nhiều Scope đan xen: Vừa sửa liên quan tới `auth` lại vừa động vào `payment`.
-3. Số file thay đổi > 10 files VÀ không chạm tới chung một chủ đề.
-4. Trộn lẫn giữa cập nhật cấu hình file (`package.json`, `.eslintrc`) với tính năng Code (`src/..`).
+**Tách (Split) NGAY NẾU:**
+1. Có cả `feat` (tính năng) và `fix` (sửa lỗi) trong cùng một rổ.
+2. Nhiều Scope đan xen: vừa sửa `auth` vừa động vào `payment`.
+3. Số file thay đổi > 10 VÀ không chung một chủ đề.
+4. Trộn cập nhật cấu hình (`package.json`, `.eslintrc`) với code (`src/..`).
 
-**Được gộp thành 1 Nhát (Single Commit) NẾU:**
+**Gộp thành 1 commit NẾU:**
 - Cùng 1 Scope/Type duy nhất.
-- Tổng số file <= 3 và tổng Line Diffs <= 50 dòng.
+- Tổng số file <= 3 và tổng diff <= 50 dòng.
 
 ## Cú pháp Bắt buộc (Conventional Commits)
 - `feat(scope): ...` — Tính năng mới
 - `fix(scope): ...` — Vá lỗi
-- `refactor(scope): ...` — Cấu trúc lại mã nhưng không làm đổi logic hành vi
+- `refactor(scope): ...` — Cấu trúc lại mã, không đổi hành vi
 - `perf(scope): ...` — Cải thiện hiệu suất
 - `chore(deps): ...` — Cập nhật thư viện
 - `docs(readme): ...` — Tài liệu
@@ -33,7 +50,9 @@ git add -A && git diff --cached --stat && git diff --cached --name-only
 
 *LƯU Ý: Tuyệt đối không dùng `docs` hoặc `chore` khi có file nằm ở `.claude` thay đổi. Hãy dùng `feat` hoặc `fix`.*
 
+Thông điệp commit không có trailer `Co-Authored-By` hay dòng ghi công AI nào, trừ khi người dùng yêu cầu trong chính lần gọi này.
+
 ## 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 `cf:develop` xử lý conflict file.
+- **Có Secret:** dừng toàn bộ như Bước 1; báo file/dòng/loại; chờ người dùng quyết định.
+- **Push bị báo Rejected:** Cấm dùng `--force`. Chạy: `git pull --rebase origin <branch>`. Chỉ push nhánh hiện tại.
+- **Merge Conflicts:** Báo "BLOCKED", liệt kê file, in lệnh để người dùng giải quyết hoặc gọi agent `cf:develop` xử lý file conflict.

package/src/claude/skills/git/references/worktree-blueprint.md

@@ -10,7 +10,7 @@ Kêu gọi lệnh Bash để kiểm tra thư mục gốc:
 git rev-parse --show-toplevel
 git branch --show-current
 ```
-*-> Giả sử top-level path là `/path/to/project` và current là `main`.*
+*-> Giả sử top-level path là `/path/to/project` và current là `dev`.* Worktree mới tạo nhánh from the current branch, trừ khi User chỉ định nhánh gốc khác. Nếu `git branch --show-current` rỗng (detached HEAD), dừng lại và hỏi User nhánh gốc.
 
 ### Bước 2: Nhận Diện & Định Tên Nhánh (Slugifier)
 Tuỳ theo `<feature-description>`, hãy sinh ra một cái tên nhánh dạng Kebab-case.
@@ -19,24 +19,44 @@ Tuỳ theo `<feature-description>`, hãy sinh ra một cái tên nhánh dạng K
 *Lưu ý: Nếu User chủ động gõ tên có sẵn mã Jira (TD-1234) hoặc tên tuyệt đối thì bỏ qua prefix Type.*
 
 ### Bước 3: Khởi Sinh Worktree (Sibling Pattern)
-**LUẬT THÉP:** Worktree KHÔNG BAO GIỜ được đặt lồng bên trong thư mục Git hiện tại để tránh git cache xung đột/rác index. 
-Luôn phải đặt cấp Sibling (`../`).
+**Mặc định luôn là cấp Sibling (`../`)**: skill không bao giờ tự tạo worktree lồng bên trong repo. Một đường dẫn lồng (dưới `.claude/worktrees/` đã bị ignore) chỉ chấp nhận khi chính người dùng hoặc công cụ host đã đặt tên và tạo ra nó; khi còn worktree lồng, không chạy `git clean -fdx` ở root repo vì nó xoá cả thư mục bị ignore.
+
+Lối tắt tùy chọn (không bắt buộc, không phải điều kiện): `claude --worktree`, Orca, Herdr. Chỉ cần `git` (thêm `rsync` cho Bước 4); máy không có công cụ nào khác vẫn làm đủ mọi bước.
 
 Cấu trúc lệnh Bash thực thi:
 ```bash
 export REPO_HOME=$(git rev-parse --show-toplevel)
 export REPO_NAME=$(basename $REPO_HOME)
+export BASE_BRANCH="${BASE_BRANCH:-$(git branch --show-current)}"
 export BRANCH_NAME="feat/add-auth"
 
 # Sanitize folder path (thay / thành - để tránh lỗi subfolder nếu k cần thiết)
 export SAFE_FOLDER_NAME="${REPO_NAME}-${BRANCH_NAME//\//-}"
 export TARGET_DIR="$REPO_HOME/../$SAFE_FOLDER_NAME"
 
-git worktree add -b "$BRANCH_NAME" "$TARGET_DIR" main || git worktree add "$TARGET_DIR" "$BRANCH_NAME"
+
+# Không che lỗi của git bằng `||`: hai tình huống đầu phải DỪNG và hỏi người dùng, không chạy tiếp, không tự chọn.
+if [ -e "$TARGET_DIR" ]; then
+  echo "Thư mục $TARGET_DIR đã tồn tại — hỏi người dùng, không chạy tiếp"
+elif git show-ref --verify --quiet "refs/heads/$BRANCH_NAME"; then
+  echo "Nhánh $BRANCH_NAME đã tồn tại — hỏi người dùng: dùng lại nhánh đó (git worktree add \"$TARGET_DIR\" \"$BRANCH_NAME\") hay đặt tên khác; không chạy tiếp"
+else
+  git worktree add -b "$BRANCH_NAME" "$TARGET_DIR" "$BASE_BRANCH"
+fi
 ```
+Nhánh đã tồn tại thì KHÔNG tự gắn worktree vào nó: nhánh cũ có thể có gốc khác `$BASE_BRANCH`, trái luật "tạo từ nhánh hiện tại".
 
 ### Bước 4: Tự Động Hóa Môi Trường (Hydration)
-Tại `$TARGET_DIR` mới, bạn phải tự scan (bằng `ls` hoặc `find`) để tìm file cấu trúc và cài đặt:
+Bộ cài CafeKit thêm `.claude/`, `.codex/`, `.agents/` vào `.gitignore`, nên `git worktree add` không mang theo hook, skill và rule. Chép những thư mục đang có ở repo gốc mà worktree mới còn thiếu, bỏ log, session state, worktree lồng của agent và môi trường cài cục bộ:
+```bash
+for dir in .claude .codex .agents; do
+  if [ -d "$REPO_HOME/$dir" ] && [ ! -e "$TARGET_DIR/$dir" ]; then
+    rsync -a --exclude 'session-state/' --exclude 'worktrees/' --exclude '.logs/' --exclude 'node_modules/' --exclude '.venv/' "$REPO_HOME/$dir/" "$TARGET_DIR/$dir/"
+    echo "hydrated $dir"
+  fi
+done
+```
+Sau đó, tại `$TARGET_DIR` mới, bạn phải tự scan (bằng `ls` hoặc `find`) để tìm file cấu trúc và cài đặt:
 - Nếu tìm thấy `.env.example`, tự chạy `cp .env.example .env`.
 - Nếu tìm thấy `bun.lockb` / `bun.lock`: Chạy `bun install`.
 - Nếu tìm thấy `pnpm-lock.yaml`: Chạy `pnpm install`.
@@ -45,4 +65,20 @@ Tại `$TARGET_DIR` mới, bạn phải tự scan (bằng `ls` hoặc `find`) đ
 ### Bước 5: Báo Cáo Chuyển Giao
 Sau khi chạy hoàn thiện qua Native Bash, xuất báo cáo cho Tướng Lĩnh.
 Nội dung thông báo (Mẫu):
-> "✅ Worktree được khởi tạo thành công tại thư mục Sibling: `/path/to/.../project-feat-auth`. Môi trường npm và .env đã được setup. Để bắt đầu code, vui lòng mở cửa sổ Terminal/IDE mới tại đường dẫn đó."
+> "✅ Worktree được khởi tạo thành công tại thư mục Sibling: `/path/to/.../project-feat-auth`, nhánh `feat/auth` tạo từ `dev`. Đã chép `.claude/` (các dòng `hydrated`). Môi trường npm và .env đã được setup. Để bắt đầu code, vui lòng mở một phiên agent mới tại đường dẫn đó, để hook của worktree này chỉ canh gói specs của chính nó."
+
+Mỗi worktree chỉ giữ một gói specs đang mở; phiên agent mới bắt đầu ngay trong thư mục worktree đó.
+
+## Vòng đời worktree: liệt kê, gỡ, dọn
+Mục tiêu: không bao giờ mất việc chưa lưu. Thư mục `.claude/`, `.codex/`, `.agents/` do Bước 4 chép sang là bản sao dùng lại được, nên không tính là việc chưa lưu; mọi thứ khác bị ignore (ví dụ `.env` đã sửa, kể cả `.env` chép từ `.env.example` ở Bước 4) thì có và phải hỏi.
+
+- **Liệt kê:** `git worktree list --porcelain`. Mục có dòng `prunable` là thư mục đã mất.
+- **Gỡ `<dir>`:** chạy hai lệnh kiểm trước, rồi mới gỡ:
+  ```bash
+  git -C <dir> status --porcelain --ignored   # bỏ qua các mục dưới .claude/ .codex/ .agents/ đã chép
+  git -C <dir> log --oneline <base>..HEAD      # <base> = nhánh worktree được tạo từ đó, hoặc nhánh tích hợp
+  ```
+  Cả hai trống → `git worktree remove <dir>` (không `--force`). Có bất cứ dòng nào → hiện ra và hỏi; chỉ gỡ sau khi người dùng gõ đúng `remove <tên-thư-mục>`.
+- **Dọn mục `prunable`:** `git worktree prune`. Không bao giờ `rm -rf` một thư mục worktree.
+- **Nhánh:** xoá bằng `git branch -d <nhánh>`; "đã merge" nghĩa là nhánh có trong `git branch --merged <base>`. Chỉ dùng `-D` sau khi người dùng gõ đúng `delete <tên-nhánh>`.
+