dowafu 0.3.2 → 0.4.0

package/publish/en/.claude/skills/preflight/SKILL.md

@@ -1,198 +0,0 @@
----
-name: preflight
-description: Before starting work in a project, check whether its environment has silently disabled the workflow: whether the workflow-specification chapter is actually readable, whether the skills and lenses are present, whether tmp/ is gitignored. Claude Code additionally checks auto-compact and the subagent model; other hosts additionally check whether dowafu runs. Read-only, report-only — changes no settings.
----
-
-# preflight — environment pre-check
-
-**Run this before using this workflow in a project for the first time.** Dispatching, implementing, and wrapping up only to discover afterwards that the environment had silently disabled the workflow means the whole stretch of work was wasted.
-
-Assume the project in front of you has **never seen any of this**: nothing may be installed, half of it may be installed, or every file may be present while you still cannot read them. Those three states must be told apart, and **none of them raises an error**.
-
-> **Read-only, report-only — do not modify any settings file.** Those belong to the user, several of them are global, and touching one affects all of their projects. Produce the list and let them decide whether, and what, to change.
-
-**This document has three sections. Everyone must check section 1; sections 2 and 3 are either/or:**
-
-| If you are | Check |
-| --- | --- |
-| Any agent | Section 1 |
-| **Claude Code** | Section 1 + **section 2** |
-| **Any other host** | Section 1 + **section 3** (the items in section 2 do not exist for you; checking them yields nothing but "not found") |
-
-> **The criterion is "who is running you", not "which model is behind you".** When Claude Code is pointed at a compatible API or another vendor's model via BYOK in `settings.json`, it **is still Claude Code** — `autoCompactEnabled` and `CLAUDE_CODE_SUBAGENT_MODEL` still apply, so use section 2. Conversely, another host running Claude as its model still uses section 3.
->
-> **When in doubt, check both**, and honestly mark anything you could not determine as "not found".
-
----
-
-## 1. Everyone must check these, whatever the environment
-
-Run the commands from the repository root. **There is no guarantee where your working directory is — `cd` there first.**
-
-```bash
-cd <absolute path to the repo root>
-
-echo "=== workflow specification ==="
-ls CLAUDE.md AGENTS.md workflow_spec.md 2>&1
-# This only locates which file holds the content. A hit here ≠ you can read it — see the criterion below.
-# Both spellings: a project may carry this chapter in another language than the pack you installed.
-grep -nE "Plan → Implement → Accept|規劃→實作→驗收" CLAUDE.md AGENTS.md workflow_spec.md 2>/dev/null
-
-echo "=== skills and lenses ==="
-ls .claude/skills/ 2>/dev/null
-ls .claude/agents/hole-finder*.md 2>/dev/null
-
-echo "=== tmp/ ==="
-git check-ignore -q tmp && echo "ignored" || echo "not ignored"
-```
-
-### Is the workflow specification readable
-
-**There is only one criterion: can you, right now, read the contents of the chapter "Plan → Implement → Accept (hub-and-spoke form)"?**
-
-**The chapter may be there under the other language's heading.** Language packs install their own copy, so a project that already had this chapter can end up with two — in two languages, only one of which auto-loads. The grep above looks for both spellings for exactly this reason; if it returns hits in more than one file, read the next paragraph before deciding anything.
-
-If you can read it, it passes. Whether the content is pasted directly into the entry file or pulled in via something like `@` is **the user's choice and outside the scope of this check**.
-
-If you cannot read it, mark it as failing, then **go find it yourself** (usually `workflow_spec.md` at the repo root), and note in your report that "the specification is not in the auto-loaded set; it was read manually this time" — so the user knows a different session will miss it again.
-
-**If you find more than one copy, say which one auto-loads.** A project may already carry this chapter inline in its entry file while a second copy sits at the repo root as `workflow_spec.md` — and the two may be in different languages, since each language pack installs its own. "The content is readable" is then not enough: report **which copy is in your context**, and that nothing keeps the two in step. The one that auto-loads is the one that governs every later session.
-
-> **Why might it be unreadable?** The entry file differs by host: Claude Code reads `CLAUDE.md` (**not `AGENTS.md`**), while most other hosts read `AGENTS.md` at the repo root. And `@xxx.md` is Claude Code's import syntax — **other hosts do not expand it**, so what you see is a single line of text and the specification never entered your context at all. That does not mean the project is misconfigured; it is a difference on your side.
-
-### Skills and lenses
-
-Whether `.claude/skills/find-holes-external/` and the lens definitions are present. **Report the filenames you actually saw, and name any that are missing** — "I saw three of them" is not a check; which three is the check.
-
-Four files are expected, and all four are normal:
-
-| File | What it is |
-| --- | --- |
-| `hole-finder.md` | The general-purpose lens |
-| `hole-finder-cost.md` | Cost |
-| `hole-finder-feasibility.md` | Feasibility |
-| `hole-finder-safety.md` | Security, concurrency, failure states |
-
-> The glob above has no hyphen before the `*` on purpose: `hole-finder-*.md` cannot match `hole-finder.md`, so counting from it while expecting four never adds up.
-
-**If a lens is missing, do not write a replacement yourself** — it is the source of the spoke's system prompt, and a self-written version puts the output out of step with the audit criteria.
-
-### `tmp/`
-
-If it is not gitignored, mark it as failing: spoke reports contain the verbatim text of the plan and would be committed into version control. **Do not edit `.gitignore` yourself** — ask the user.
-
----
-
-## 2. If you are a Claude Code agent
-
-**If you are going to dispatch externally (`/find-holes-external`), items one and four of §3 apply to you too** — the CLI has to be runnable and configured no matter which host is driving it. The rest of §3 is about hosts other than this one.
-
-The two items below affect **only Claude Code's own in-process sub-agents**. For external dispatch (`find-holes-external` via `dowafu`), the spoke's model is decided by the ticket's `_dispatch.md` and is **unaffected by either of them** — if this project only uses external dispatch, checking this section changes nothing.
-
-```bash
-cd <absolute path to the repo root>
-
-echo "=== settings (lowest to highest precedence) ==="
-for f in ~/.claude/settings.json .claude/settings.json .claude/settings.local.json; do
-  [ -f "$f" ] && { echo "--- $f"; cat "$f"; }
-done
-
-echo "=== environment variables ==="
-echo "DISABLE_AUTO_COMPACT=${DISABLE_AUTO_COMPACT:-(unset)}"
-echo "CLAUDE_CODE_SUBAGENT_MODEL=${CLAUDE_CODE_SUBAGENT_MODEL:-(unset)}"
-
-echo "=== models declared in agent definitions ==="
-grep -H "^model:" .claude/agents/*.md 2>/dev/null || echo "(no agent definitions, or none specify a model)"
-
-echo "=== main model and effort ==="
-grep -h "\"model\"\|\"effortLevel\"" ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null || echo "(unset, using defaults)"
-```
-
-### auto-compact
-
-**`autoCompactEnabled` not appearing at any settings layer = failing**, because its default is `true`. Do not read "I did not see the setting" as "there is no problem" — that makes this check pass forever.
-
-The workflow specification requires handing off via `/wrap` and restarting the session when context runs short, rather than compacting (compaction is lossy, and once compacted a hot session has no value left).
-
-Related: `autoCompactWindow` (100000–1000000) and the environment variable `DISABLE_AUTO_COMPACT`.
-
-### The subagent model
-
-`settings.json` has **no** "default subagent model" key — but **one environment variable overrides everything**. Resolution runs through four layers, highest to lowest; **lay all of them out for the user**:
-
-1. **The `CLAUDE_CODE_SUBAGENT_MODEL` environment variable** (when set to an alias or a model ID)
-2. The `model` parameter passed on each call
-3. The `model:` frontmatter in `.claude/agents/*.md` (or `~/.claude/agents/`)
-4. The main conversation's model (which is also the default when the frontmatter omits it)
-
-**Layer 1 overrides the `model:` in every agent definition file**, including the ones deliberately set to opus — that is the "set it once and every in-process dispatch turns into a lightweight model" case. And it is **global: setting it in project A affects project B**.
-
-The `availableModels` allowlist then filters the three layers above: a blocked family alias is swapped for the newest permitted version of that family, and in every other case it **falls back to inheriting the main conversation's model**. So `model: opus` in the frontmatter **does not guarantee opus runs**.
-
-**Checking only one of those layers and reporting "all fine" misses the most common case.**
-
-**The consequences of a downgrade are silent**: every in-process sub-agent becomes a lightweight model, hole-finding still runs, still produces output, still wraps up — the quality simply drops, and nothing anywhere flags it.
-
----
-
-## 3. If you are not a Claude Code agent
-
-The two items in section 2 do not exist for you; skip them. What you need to confirm is the four things below, **in this order** — if an earlier one does not hold, checking the later ones is pointless.
-
-### One: where `dowafu` is, and whether it runs
-
-**This is the precondition.** If the tool will not start, no ticket however well written can be dispatched; discovering it at dispatch time wastes a whole round of ticket assembly.
-
-```bash
-dowafu --version
-```
-
-Printing a version number passes. Failing to print one means exactly one of two things:
-
-| Symptom | What it means | How to report it |
-| --- | --- | --- |
-| `Operation not permitted` | **The sandbox is blocking it**, not a missing install. The CLI usually lives under the home directory, and sandboxes do not read the home directory by default | Retry after allowing it per your host's prompt. Also tell the user that the API key (`~/.config/dowafu/.env`) and outbound network are blocked the same way and will need allowing at dispatch time |
-| `command not found` | It may not be installed, or it may be installed outside PATH | Ask the user where the CLI is installed (have them run `which dowafu`); **do not go searching the filesystem yourself** |
-
-**`command -v dowafu` finding nothing does not mean it is not installed** — do not use that as the criterion.
-
-**A command that neither returns nor errors is a third case: it is waiting.** Without `--yes` the CLI prints a confirmation prompt and blocks on stdin; depending on the host that surfaces as a timeout, as silence, or as an offer to send input on your behalf. Note which one your environment does — you will meet it again at dispatch time, and that is a much worse moment to find out.
-
-### Two: whether the lens definitions and skills are present
-
-See "skills and lenses" in section 1. One point matters especially for you:
-
-**The lens definitions are for the CLI to read, not for you.** They are the source `dowafu` uses to assemble the spoke's system prompt; you only need to confirm the **files exist**, not understand their contents. The skills are what you read.
-
-### Three: the workflow specification's content, somewhere you can read it
-
-See "is the workflow specification readable" in section 1; the criterion is the same: **can you, right now, read the contents of that chapter.**
-
-**You are more likely than Claude Code to trip on this one**, so it is worth a second look. `@xxx.md` is Claude Code's import syntax and you will not expand it — if the entry file contains only that line, what you see is one line of text, and **you may well believe you have already read the specification**. Actually check whether that chapter's content is in your context; do not go by impression.
-
-### Four: is the CLI configured — `dowafu --doctor`
-
-```bash
-dowafu --doctor
-```
-
-It prints where the config directory resolved to, whether `.env` is there, **which providers have a key** (presence only — it never prints a value), the bundled model whitelist, and which lens definitions it found. It calls no API and costs nothing, and it needs no ticket, which is what makes it usable before anything else exists.
-
-Report the missing rows as they are printed. **Do not offer to write the key for the user, and do not ask them to paste one into this conversation** — whatever is pasted here stays in this conversation's history. Creating the directory and an empty template is fine; the value itself is theirs to type into the file.
-
-A `dowafu --doctor` that prints nothing but an error is the same finding as item one: the CLI is not runnable from here, and nothing below it matters yet.
-
----
-
-## 4. Output
-
-One table, one page at most:
-
-| Item | Status | Current state | How to fix |
-| --- | :-: | --- | --- |
-| Workflow specification | ✗ | The "Plan → Implement → Accept" chapter is not in my context; I have read `workflow_spec.md` manually to cover it | To have it auto-load every session, the entry file's wiring needs adjusting |
-| `tmp/` | ✓ | Ignored by `.gitignore` | — |
-
-**State at the top of the table which kind of host you are and whether you followed section 2 or section 3**, so the user does not assume the unchecked items were checked.
-
-**Mark "not found" separately from "passes".** When a file cannot be read, or an item cannot be determined, say so honestly rather than counting it as a pass — the reason this skill exists is to catch silent failures, and silently failing yourself defeats the purpose.

package/publish/en/.claude/skills/wrap/SKILL.md

@@ -1,61 +0,0 @@
----
-name: wrap
-description: Wrap-up and pre-acceptance checks for an implementation session — self-check that the project's completion conditions are all green, confirm report/runbook/issue_log are in place, produce the user's manual-test checklist and a diff-versus-plan summary, and advise switching sessions (never compacting). Use when an implementation session finishes, or when context runs short.
----
-
-# wrap — implementation wrap-up
-
-You are an implementation spoke, wrapping up. First decide which mode you are in:
-
-- **Completion wrap-up** (default): the work items are done → follow sections 1–4.
-- **Mid-work handoff**: context is running short and the work is not done → go straight to section 5 ("all green before finishing" does not apply).
-
-## 1. Self-check that everything is green
-
-The completion conditions are **whatever that project's AGENTS.md defines**. If it defines none, look at `scripts` in `package.json` and **run whichever exist** (`test` / `lint` / `typecheck` / `build`).
-
-- **Do not add tooling just to make the list look complete** (if the project has no linter, do not install ESLint)
-- **Do not skip an existing script because it "looks unnecessary" either**
-
-Two execution details:
-
-- Run tests **only for the modules you changed this round**; see that project's AGENTS.md testing rules for how to scope it. Never pipe into `| sort` / `| head` / `| tail` — that swallows the failure output
-- If `typecheck` and `build` are two separate scripts, **run them separately, never merged**. Build configs commonly exclude test files, so only typecheck covers them; merged, you also lose the ability to tell "the build broke" from "a test has a type error"
-
-If any of them is not green: fix it before continuing the wrap-up. **Never finish in the red.**
-
-## 2. Document check
-
-- **report**: produced? Does it have a "corrections made during implementation" section (where the implementation deviated from the plan)?
-- **runbook**: produced? Does it contain manual steps for the parts a machine cannot test (environment, paths, order of operations, expected results)?
-- **issue_log**: is every fix made after this round's report was produced logged, one entry per fix? (report/runbook are not edited retroactively — see the document discipline in AGENTS.md)
-
-## 3. Produce the acceptance package (the final message to the user)
-
-Present it in this order:
-
-1. **Manual-test checklist**: extract from the runbook the items the user has to verify by hand and list them one by one (steps + expected result). Do not make the user go dig through the runbook.
-2. **Diff-versus-plan summary**: the list of files actually changed against the list of files in the plan, matched up one by one; **explicitly flag anything changed beyond the plan** (smuggling is an acceptance red line).
-3. **Open items**: problems found during implementation but not handled (logged in issue_log for later, or needing the user's ruling).
-
-## 4. Wrap-up reminders
-
-- **Do not recommend committing** — per the Git safety rules in AGENTS.md, present the diff to the user for confirmation first.
-- **Do not compact**: if context is already tight, say so plainly — "this session should finish here; later fixes can reuse this session (hot patching); if this session has gone cold or been cut, open a new one and cold-start from report + issue_log".
-- During a patch wave: append to issue_log per fix.
-
-## 5. Mid-work handoff (context running short, work unfinished)
-
-**Do not compact** — after compaction the map has been lossily squeezed and a hot session has lost its value; write the handoff document instead, then close the session.
-
-1. Update the todo statuses (done / in progress / untouched).
-2. Write the handoff document `_docs/<area>/handoff_<topic>.md` (the first one carries no version number; later ones are `handoff_<topic>_v<n>.md`).
-   **One new file each time — never append to the old one.** The old one stays as history and is not edited.
-   The header states the date, why the handoff is happening, the branch state, and **a link to the previous one plus what it supersedes** (for example: "previous: `handoff_<topic>_v4.md` — its content is complete; this file supersedes it"). The body covers:
-   - The plan's path, and which work item you got to
-   - The list of half-finished files and the state of each (for example: "X.ts changed, untested"; "Y.ts half changed, missing Z")
-   - The current red/green state (which tests pass, which fail, and why)
-   - The next step (specific down to "open which file and do what")
-   - Environment notes and traps (dev server port, flaky tests, workarounds)
-3. Fixes completed this round still go into issue_log as usual.
-4. Give the user a one-line resume command: "New session opener: `continue per <plan path>; first read <handoff path> and issue_log`".

package/publish/en/README.md

@@ -1,106 +0,0 @@
-# publish/ — the things meant to be copied into another project
-
-Three kinds, each landing in a different place:
-
-| Here | Lands in the target project at | What it is |
-| --- | --- | --- |
-| `.claude/skills/<name>/` | `.claude/skills/<name>/` | Skills — for hosts that read this directory |
-| `.agents/skills/<name>/` | `.agents/skills/<name>/` | The same skills, for hosts that read the open spec directory |
-| `.claude/agents/*.md` | `.claude/agents/` | Lens definitions — the source of each spoke's system prompt |
-| `workflow_spec.md` | Project root | The plan → implement → accept workflow specification |
-
-> **Do not relocate `.claude/agents/`.** That path is hardcoded in the CLI (`.claude/agents`
-> under `--repo-root`) and has nothing to do with where your host reads from — the tool
-> reads it, not the agent.
-
-## Installation
-
-```bash
-TARGET=<path to the target project>
-mkdir -p "$TARGET/.claude/skills" "$TARGET/.claude/agents" "$TARGET/.agents/skills"
-cp -R .claude/skills/. "$TARGET/.claude/skills/"
-cp -R .agents/skills/. "$TARGET/.agents/skills/"
-cp .claude/agents/*.md "$TARGET/.claude/agents/"
-cp workflow_spec.md "$TARGET/"
-```
-
-**Every file is overwritten whole**; there is no part that needs to be spliced together by hand.
-
-> **Copy both `.claude/` and `.agents/` — do not skip `.claude/` on the grounds that "this
-> project doesn't use Claude".** The `agents/` directory underneath is the CLI's data
-> directory: the tool reads it, regardless of which agent you happen to use. If you skip it,
-> a dry run aborts and prints the path it could not find (so it costs nothing), but you will
-> have to come back and do it anyway.
-
-Once installed, run **`preflight`** in the target project — it checks whether the wiring is
-in place and whether the environment has silently disabled the workflow. These failures
-**never raise an error**; they just quietly stop the workflow from taking effect.
-
-**Skills are not guaranteed to be `/` commands.** Some hosts mount both directories
-automatically and offer `/<name>`; some offer neither. If you cannot invoke it that way, name the file
-directly: "follow `.agents/skills/preflight/SKILL.md`".
-
-### How the two copies of each skill relate
-
-The copy under `.agents/skills/` is derived from the one under `.claude/skills/` — **same
-content, minus the passages that hold only for one particular host**. Its frontmatter
-`metadata` records the sha256 of the source file, so if the source changes and the derived
-copy does not follow, the pre-publish check will stop it. **Always edit the copy under
-`.claude/skills/`**, then revisit the derived one.
-
-## Wiring `workflow_spec.md` into the target project
-
-Claude Code **reads `CLAUDE.md`, not `AGENTS.md`**; and the `AGENTS.md` spec itself
-**defines no import mechanism at all**. Both readers have to be addressed separately, or one
-of them silently misses the entire specification.
-
-Add this at the end of the target project's `AGENTS.md`:
-
-```markdown
-## Workflow specification
-
-See `workflow_spec.md` (project root). The `@` on the next line is Claude Code's import
-syntax and loads that file automatically; other tools must open it directly.
-
-@workflow_spec.md
-```
-
-Three details that raise no error when you get them wrong — they just quietly do nothing:
-
-- **The `@` must not be wrapped in backticks** — wrapped, it is literal text and imports nothing
-- The path is **relative to the file containing the import**, not to the working directory
-- Imports can recurse, up to **four levels**; `CLAUDE.md` → `AGENTS.md` → `workflow_spec.md` is two
-
-If the target project has no `CLAUDE.md`, create one containing the single line `@AGENTS.md`
-(the officially recommended approach).
-
-### If the project already has a workflow-specification chapter
-
-Plenty of projects already carry one, pasted straight into the entry file — and possibly in
-a different language from the pack you just installed, since each language pack ships its
-own `workflow_spec.md`. Copying the file in on top of that leaves **two copies with nothing
-keeping them in step**, and the one that governs every session is whichever the entry file
-auto-loads: the chapter that was already there, not the file you just installed.
-
-Pick one and remove the other:
-
-- **Keep `workflow_spec.md`** (recommended): delete the old chapter out of the entry file
-  and put the import above in its place
-- **Keep the inline chapter**: replace its text with the installed `workflow_spec.md`'s, in
-  whichever language you are standardizing on, and do not copy `workflow_spec.md` into the
-  project at all
-
-Either way the project ends up with **one copy**. Run `preflight` afterwards: it reports
-which copy is actually in context, so a skipped decision here still gets caught.
-
-## What must never appear here
-
-The contents of `publish/` run somewhere that has no idea the source project exists, so they
-must not contain absolute paths, the source project's name or its document filenames, commands
-that only work in the source project, or measured figures and sample-size discussion (those
-are evidence, not operating instructions).
-
-One exception: the name `_docs/` may appear — it is the CLI's hardcoded spoke-forbidden
-directory, a tool-level reserved name.
-
-Run the source project's pre-publish check before syncing; it sweeps for all of the above.

package/publish/en/workflow_spec.md

@@ -1,71 +0,0 @@
-# Workflow Specification
-
-## Plan → Implement → Accept (hub-and-spoke form)
-
-> A planning document is a lossy projection of the decision process; whoever holds the live context is the cheapest one to do the work. This section is organized accordingly: planning and rulings stay in the hub, where the context lives; execution goes to ticket-driven spokes; quality calls are settled by numbers.
-
-### Roles
-
-| Role | Responsibility | Authority |
-| --- | --- | --- |
-| **User** | Whether to do it, the goal, state changes (start / block / terminate) | Discretion needs **no justification**; one sentence takes effect |
-| **hub** (the long conversation holding the context) | Keeping discussion focused, writing plans, issuing tickets, merging spoke reports, comparing outcomes against the original intent and analyzing the gaps | **Versions are cut only from the hub** |
-| **spoke** (ticket-driven session) | Implementation (= review + implement), measurement (benchmark), hole-finding (optional) | No version authority, no status field, no ruling authority |
-
-### Flow overview
-
-```
-0. Decision discussion (hub + user) → decision document
-1. Planning (hub, per the MUST checklist) → plan document → user approves directly
-   (Optional: the user calls for hole-finder spokes — need-to-know tickets, producing
-    observations rather than verdicts; skills: `/find-holes-external` for external
-    dispatch, `/find-holes` for in-process sub-agents)
-2. Implementation (spoke, opening with "implement per document X") → done when
-   `pnpm run test`/`lint`/`tsc`/`build` are all green → report + runbook
-   (wrap-up skill: /wrap)
-3. Hot patching (same session, kept alive until the patch wave ends) → append to
-   issue_log per fix; do not retroactively sync report/runbook
-4. Acceptance (user): behavioral acceptance (manual test per the runbook) + diff review
-   (faithful to the plan, nothing smuggled in) + business judgment → commit/PR
-```
-
-### Document discipline
-
-- Six document types, each with one job: **decision** records why / **plan** records how / **facts** (append-only) records verified facts / **report** records delivery state (not edited after it is produced) / **runbook** records manual test steps / **issue_log** records the patch ledger (append-only; messy is normal).
-- A new version writes only the differences; background gets one line citing the decision document, never a restatement.
-- Changing a document's status field is the user's authority alone; **a document must not define its own conditions for being overturned** ("this document can only be superseded by X" is a red flag).
-
-### Three sourcing rules (against smuggling)
-
-1. "Per the user's ruling / already settled" **must carry its source** (the exact words, when, and what question it answered); without a source it counts as unsettled. Procedural replies ("not yet", "hold on") must never be promoted into substantive decisions.
-2. An acceptance threshold **must carry its derivation** (a measured baseline from the same mechanism, or a number the user specified); a number the model made up is invalid. The baseline used to calibrate a threshold must come from the same mechanism — change two variables at once and the threshold is the first thing to break.
-3. Citing precedent **hands over the ruler, not the corpse**: a ruling transfers only under "same problem + same cost structure"; "that one died, so this one will too" is not an argument.
-
-### Quality-bet clause
-
-Choices of model, prompt, or calling mechanism are settled by benchmark: fix the threshold beforehand, never relitigate it afterward; do not force adoption of something that missed the threshold; file negative results together with the result files, and any later proposal of the same kind must first address the existing measurements.
-
-### Implementation-session discipline
-
-- Open by listing todos (TodoWrite — the anchor that survives context compaction); delegate large read-heavy reconnaissance to sub-agents (a context firewall).
-- **Do not use compact** (it is lossy, and once compacted a hot session has lost its value): when context runs short → wrap up at the last natural breakpoint — if the work is done run `/wrap`; **if it is not done run `/wrap` in handoff mode** (write a handoff document `handoff_<topic>.md`; each later handoff opens a new versioned file `handoff_<topic>_v<n>.md` whose header states which one it supersedes — never append to the old one) → close the session → a new session cold-starts from the plan plus the handoff. If a conversation opens with "This session is being continued" → re-read the plan; do not trust the specifications in a summary.
-  **Whether context is "running short" is the user's call — do not declare it on your own hunch.** A model cannot measure its own context, and subjective judgments produce far more false alarms than hits. Unless the user says so, or there is an actual number, only mention "want to wrap up?" at a natural breakpoint — do not keep raising it, and above all do not interrupt work in progress because of it.
-- Deviating from the plan during implementation → record it in the report (the "corrections made during implementation" section); incidental fixes in a file you are already touching (an unrelated lint error, say) are allowed — log them in issue_log.
-
-### MUST checklist when writing an implementation plan
-
-Every item below needs an explicit answer in the plan, or an explicit note that the gap is a **deliberately accepted trade-off**. None may be left blank:
-
-1. **Citing means verifying**: every claim of "the existing mechanism already covers this / zero changes needed / there is already an X filter" requires actually opening that file and following the **complete semantics** through (branches, unions/side tables, fallback paths) — a filename, a comment, or a line number is not enough. When citing, include the key semantics that support the conclusion, not just the location.
-   **This rule applies equally when you are accepting a spoke's citations** (in-process and external alike): verifying "the comment the spoke quoted does exist" is not enough — you must also verify "**whether what the comment says still holds**", because comments drift away from the code. A real case: a spoke cited a file-header comment claiming "this component sits outside the provider's scope"; the hub confirmed the comment existed and matched word for word, and judged the claim factually correct — but that architecture had long since been moved inside the provider, and **the conclusion was wrong**.
-2. **Failure states and time windows**: for each mechanism, write down what happens when it fails — before the scheduled job has run? after retries are exhausted? under a concurrency race? "At most N times" with nothing after it about "and when they are used up…" is an unfinished design.
-3. **Gate ordering for billable calls**: for any call that incurs external API cost (LLM / STT / image generation / embedding), the quota or gate check must come **before** the call; "count it only after success" additionally requires a read-only pre-check up front, and must answer "what happens on each request after the limit is hit, and what does it cost".
-4. **New-endpoint protection is mandatory**: any new API route must explicitly state its auth level, rate limit, and request-body size cap — all three; "not needed" also has to come with a reason. If the project already has a fix for a vulnerability of the same shape, cite that document as the standard.
-5. **Implementability check**: for every "the backend validates X / the code guarantees Y", answer whether the backend can technically do it and what it depends on; where it cannot, replace it with something implementable (for example a two-stage design: a coarse pre-filter followed by an exact decision).
-6. **Bidirectional lifecycle**: any "list/delist, enable/disable, expiry" mechanism needs both directions defined (writing the delisting scan but not the listing backfill = a gap); and for index-like derivatives (embeddings, variants, caches, projections), state whether they all follow along when the state changes.
-
-### Independent review
-
-Plans are not sent to any independent session for review, and restoring that practice must not be proposed; the "guidance for the review gate" found in historical `_docs` no longer applies. A clean perspective exists solely in the form of hole-finder spokes (see the two skills in step 1 of the flow overview).
-
----