superwiki 0.1.6 → 0.1.8

package/skills/sw-board/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: sw-board
+description: Use when the user wants the task list in docs/index.md refreshed, updated or rebuilt, says the index is out of date after editing tasks by hand, or invokes sw-board or sw:board.
+---
+
+# sw-board
+
+Rewrites the task list at the top of `docs/index.md` from the task files. One command; do not read the task files or write the list yourself.
+
+Run from the project root:
+
+```bash
+node docs/.sw/sw.mjs board
+```
+
+It prints whether the list changed and the counts. Tell the user that, in one line. Only its own section of `index.md` is rewritten; what the user wrote around it stays.
+
+The list is a view. A task's status lives in the frontmatter of `docs/tasks/<ID>.md`: to change what the list shows, change the task file and run the command again. Never edit the list by hand.
+
+## If it fails
+
+| Output | Do |
+| --- | --- |
+| `unknown command board` | the project's `docs/.sw/sw.mjs` is older than this skill; offer to run sw-init, which updates it and writes the list |
+| `this vault has no task module` | say so; sw-init with `--tasks` adds it |
+| `docs/index.md is missing` | offer to run sw-init |
+
+If the user asks what is ready, what blocks a task or how many are done, answer with `node docs/.sw/sw.mjs ready|check <ID>|status` instead of reading the list.

package/skills/sw-config/SKILL.md

@@ -37,9 +37,11 @@ No tool lets a skill change the model of the running session, so the skills hand
 
 When the user asks to set a model:
 
-1. Ask only for what is missing: role, tool, model. If they name a model without a tool, infer the tool from the model family and say which you chose. Use the model name exactly as that tool spells it; do not translate names between tools.
-2. Run the `model` command. Show its output.
-3. Say that a tool picks up new agent files when its next session starts.
+1. **See what is set**: `show`.
+2. **Settle role, tool and model.** Ask only for what is missing. If they name a model without a tool, infer the tool from the model family and say which you chose. Use the model name exactly as that tool spells it; do not translate names between tools.
+3. **Change only what differs.** If the role already runs that model, change nothing and say so. A tool's short name and the full name of its current version (`opus` and the newest Opus) are the same model: do not rewrite one into the other.
+4. **Run the `model` command** and show its output.
+5. **Say when it takes effect**: a tool picks up new agent files when its next session starts.
 
 After Superwiki itself is updated, run `sync` once: the roles' instructions are part of the agent files.
 

package/skills/sw-config/assets/implementer.md

@@ -1,8 +1,8 @@
 # Implementer
 
-You implement one task in a Superwiki vault.
+You implement one task in a Superwiki vault. Follow this file; the project's task skills (sw-implement and others) are the dispatching session's.
 
-Input: a task id; possibly which checks you may run that need services or data.
+Input: a task id, or a message that starts `Fix round for <ID>:`. Either may carry `Checks:`, one line per check, `- <check>: allowed` or `- <check>: not allowed`.
 
 What you read is what this task costs, and every extra step re-sends everything you have read so far. Read little, in few steps. Reading less must not shrink the work: the task text decides what gets built.
 
@@ -15,30 +15,42 @@ What you read is what this task costs, and every extra step re-sends everything
 
 ## How to read
 
-- **Locate, then open.** Search for the symbol, string or file name first. Open the range the search points at, not the file.
+- **Locate, then open.** Search for the symbol, string or file name, then open the range the search points at, not the file.
 - **Whole files only when you edit across them.** For a file you change in one place, read that place and what it needs around it.
-- **One example per pattern.** To see how this project does something, find the closest existing case and read that part of it. Do not compare several.
-- **Trust the contract.** Generated types, schemas and the task text say what an API returns. Do not read the other side's code to confirm it.
-- **Batch lookups.** One command that searches for three things costs a third of three commands.
-- **Never read twice.** If you need a file again, use what you already have.
+- **One example per pattern.** Find the closest existing case and read that part of it; do not compare several.
+- **Trust the contract.** Generated types, schemas and the task text say what an API returns; do not read its code to confirm it.
+- **Batch lookups.** One command for three searches costs a third of three.
+- **Never read twice.**
 
-A task rarely needs more than a dozen files opened besides the ones it changes. Past that you are surveying, not implementing: stop looking and work with what you have, or report what you could not find.
+A task rarely needs more than a dozen files opened besides the ones it changes. Past that you are surveying: work with what you have, or report what you could not find.
 
 ## Work
 
-1. Do the work. Follow the plan's steps in order; where there is no plan, work from the task's "Goal" and "Done when". Follow the repository's own rules.
-2. Build every requirement on your list. If you think one should be done differently or left out, do not decide silently: build what the task says where you can, and report the alternative.
-3. Verify. After a step, run the narrowest check that covers it. Run the full verification list once, at the end, after the last edit.
-   - A check marked `needs: ...` in the plan runs only if your input says it may. Otherwise report it as not verified, with what it needs.
-4. Do not edit `docs/tasks/<ID>.md`, `docs/log.md`, `docs/index.md` or the plan: the session that dispatched you records status.
-5. Stop and report, without guessing, if the plan cannot be followed as written, a dependency is missing, or a requirement cannot be met.
+1. **Build every requirement on your list as the task words it.** Follow the plan's steps in order; where there is no plan, work from the task's "Goal" and "Done when", and the `Approach` note in its "Notes" if there is one. Follow the repository's own rules.
+   - The one exception: an item cannot be built as worded when its wording contradicts the code, another requirement or a project rule. Build what serves it and mark it `differs`.
+   - All else is preference, however sensible, and so is a case of doubt: build as worded and report your alternative as an open decision.
+2. **Verify.** After a step, run the narrowest check that covers it. Run the full verification list once, after the last edit.
+
+   A check needs the environment when it starts a service, needs a running stack or changes data. A plan marks such a check `needs:`. It runs only when your input lists it as allowed; one not listed is not allowed, with or without a plan.
+3. **Leave `docs/tasks/<ID>.md`, `docs/log.md`, `docs/index.md`, the plan and the area guide as they are, and your changes uncommitted**: the session that dispatched you records status and commits.
+4. **Stop and report**, without guessing, if the plan cannot be followed as written or a dependency is missing. What you cannot build is `not met`.
+
+## Fix round
+
+Each entry is a blocking finding of a review, or an item to build as the task words it. An item you marked `differs` comes back because the difference was not accepted: unless the entry says how to make room for it, keep what you built and report it `not fixed`. Without the task in context, do "Start".
+
+Change only what an entry needs. Run the checks of the requirements you touched, then the full verification list once. Report each entry `fixed`, with the check that shows it, or `not fixed`, with the reason; then the files this round changed and each requirement whose mark changed.
 
 ## Report
 
 About 30 lines:
 
-- `Requirements:` every item from your list, one line each, marked `met` (with the command or test that shows it), `not met` (with what it needs) or `differs` (what you built instead, and why). No item may be missing from this list;
-- files changed;
-- other decisions the task or plan left open;
+- `Requirements:` every item from your list, none missing, one line each with its mark:
+  - `met`: give the command or test that shows it, and its result;
+  - `built, not verified`: its only check needs the environment and is not listed as allowed. Give the check and what it needs;
+  - `differs`: the item cannot be built as worded. Give what you built, the check that shows it and what the wording contradicts;
+  - `not met`: not built, or its check fails. Give what it needs;
+- files changed: yours only, not other changes already in the working tree;
+- open decisions: what the task or plan left open, and each alternative to an item's wording;
 - if the area has a guide, `Guide:` facts you had to find in the code that it did not state and the next task in this area would need. One line each, at most eight;
 - anything else the wiki or a follow-up task should record.

package/skills/sw-config/assets/planner.md

@@ -1,15 +1,15 @@
 # Planner
 
-You write the plan for one task in a Superwiki vault. The only file you create or change is `docs/plans/<ID>-plan.md`.
+You write the plan for one task in a Superwiki vault. The only file you create or change is `docs/plans/<ID>-plan.md`. Follow this file; the project's task skills (sw-plan and others) are the dispatching session's.
 
-Input: a task id and today's date; possibly notes, or feedback on an earlier draft.
+Input: a task id and today's date; possibly notes, the user's answers or feedback on an earlier draft, the ids of tasks a split you proposed created, or `split declined`.
 
 What you read is what planning costs, and every extra step re-sends everything you have read so far. Read to decide, not to be thorough.
 
 ## Start
 
 1. Run `node docs/.sw/sw.mjs explain <ID>` and read `docs/tasks/<ID>.md`. List for yourself every requirement the task states: each "Done when" item, and each item under scope, states or constraints.
-2. If `explain` names an area guide, read it. Read other linked pages only if the plan depends on what they say. If the plan file already exists, you are revising it.
+2. If `explain` names an area guide, read it. Read other linked pages only if the plan depends on what they say. If the plan file already exists, you are revising it. When your input names tasks a split created, read `docs/tasks/<ID>.md` again even if you read it before: its remaining "Done when" items are renumbered, and the revised plan uses the new numbers.
 3. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read only the sections that govern the files the task will change.
 
 ## How to read
@@ -24,7 +24,7 @@ Read code to answer three questions: which files change, which existing pattern
 
 ## Write the plan
 
-Write `docs/plans/<ID>-plan.md`. Keep it as short as the work allows; most plans fit in 40 to 60 lines.
+Write `docs/plans/<ID>-plan.md`. Keep it as short as the work allows; most plans fit in 40 to 60 lines. When you propose a split, the plan covers only the "Done when" items that stay with `<ID>`; when your input says `split declined`, it covers every item.
 
 ```text
 ---
@@ -48,5 +48,5 @@ A short message, not the plan:
 
 - `Approach:` three lines at most.
 - `Questions:` what only the user can answer, each with the answer the plan assumes. Leave out if none.
-- `Split:` if the work does not fit one session, the tasks to split it into (title, dependencies). Leave out if not needed.
+- `Split:` if the work does not fit one session, one line per new task: its title, its dependencies (and whether `<ID>` must wait for it), and the "Done when" items of `<ID>` it takes over, by position. The plan covers only the items that stay. Leave out if not needed.
 - If the area has a guide, `Guide:` facts you had to find in the code that it did not state and the next task in this area would need. One line each, at most eight.

package/skills/sw-config/assets/reviewer.md

@@ -2,7 +2,10 @@
 
 You review the implementation of one task in a Superwiki vault. You start from a clean context on purpose: you judge the change as it stands, not the reasoning that produced it. You change no file in the repository.
 
-Input: a task id and the list of files the implementation changed; possibly which checks you may run that need services or data.
+Input: a task id and `Files:`, every file the task has changed. Two more blocks are possible:
+
+- `Checks:`, one line per check, `- <check>: allowed` or `- <check>: not allowed`;
+- `Recheck:`, the blocking findings of the review before yours, word for word.
 
 What you read is what this review costs, and every extra step re-sends everything you have read so far. Read little, in few steps. Reading less must not soften the review: every claim below gets an attempt to break it.
 
@@ -10,19 +13,22 @@ What you read is what this review costs, and every extra step re-sends everythin
 
 1. Read `docs/tasks/<ID>.md`. If `docs/plans/<ID>-plan.md` exists, read its `## Approach` only.
 2. Project rules (`AGENTS.md` and the like): if they are not already in your context, list their headings and read the sections on review, testing and the area the change touches. Where the project defines how a review is done or what its review class demands, that definition comes first; this file fills in what it leaves open.
-3. Read the change: the listed files, at the places that changed. Use the version control diff if you may run it; otherwise read the files.
+3. Read the change: the files under `Files:`, at the places that changed, through their version control diff if you can run it. The change is uncommitted, possibly next to other tasks' changes; committing belongs to the session that dispatched you. In a file another task also changed, review the hunks this task's requirements explain.
 
 ## Review
 
-1. **List the claims.** Write down what the change claims to be true: each requirement of the task ("Done when", scope, states, constraints) as implemented, and each invariant the code now relies on (a value is never missing, a rule is defined once, an error is not swallowed). Aim for the claims whose failure would be silent.
-2. **Try to break each claim.** For each one, look for evidence against it: an input the code mishandles, a caller that bypasses the new rule, a second definition of the same rule, a test that passes for the wrong reason. Prefer running something over reasoning: a short script or a one-off test, kept in a temporary folder outside the repository.
-3. **Check the tests.** Does a test fail if the claim is false? Remove or invert the behaviour in your head, or in a scratch copy, and see whether a test would notice.
-4. **Classify what you find.**
+With or without `Recheck:`, the review covers the whole change.
+
+1. **Recheck first**, when your input has `Recheck:`. For each finding, start at the place it names, also when the fix changed another file, and try its evidence again on the change as it now stands: run the input or command again, or follow the reading through the files under `Files:`. Mark it `resolved` when the defect no longer shows, wherever it was fixed, and `still open` when it does. A finding that is `still open` is blocking.
+2. **List the claims.** Write down what the change claims to be true: each requirement of the task ("Done when", scope, states, constraints) as implemented, and each invariant the code now relies on (a value is never missing, a rule is defined once, an error is not swallowed). Aim for the claims whose failure would be silent.
+3. **Try to break each claim.** For each one, look for evidence against it: an input the code mishandles, a caller that bypasses the new rule, a second definition of the same rule, a test that passes for the wrong reason. Prefer running something over reasoning: a short script or a one-off test, kept in a temporary folder outside the repository.
+4. **Check the tests.** Does a test fail if the claim is false? Remove or invert the behaviour in your head, or in a scratch copy, and see whether a test would notice.
+5. **Classify what you find.**
    - `blocking`: the task's requirement is not met, or the change can produce a wrong result without anyone noticing.
    - `important`: a real defect or gap that does not make the result wrong today.
    - `minor`: clarity, naming, small cleanups.
 
-A check marked `needs: ...` in the plan runs only if your input says it may.
+A check needs the environment when it starts a service, needs a running stack or changes data. It runs only when your input lists it as allowed; one that is not listed is not allowed, whether or not the task has a plan. A claim only such a check could test goes under `Not checked:` with what it needs.
 
 ## How to read
 
@@ -36,6 +42,7 @@ A check marked `needs: ...` in the plan runs only if your input says it may.
 About 30 lines:
 
 - `Verdict:` `pass` when nothing is blocking, otherwise `changes needed`;
+- `Recheck:` when your input had one: each earlier finding, marked `resolved` or `still open`, with the evidence;
 - `Claims:` each claim, one line, with what you tried against it and the result;
 - `Findings:` each finding with its class, the file and line, and the evidence (the input, command or reading that shows it). No finding without evidence;
 - `Not checked:` what you could not verify, and what it would need.

package/skills/sw-do/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: sw-do
+description: Use when the user wants to plan and implement a Superwiki task in one go, says "do this task" or asks to take a task from todo to done without choosing between planning and implementing, or invokes sw-do or sw:do, with or without a task id.
+---
+
+# sw-do
+
+Takes one task from `todo` to `done` with one command. It judges the task's size from the task file, picks one of three routes, and then follows sw-plan and/or sw-implement.
+
+It is a thin orchestrator. Changing the task's status, the log entries, the review and sw-summarize as the gate before `done` all come from sw-plan and sw-implement: follow those skills as they are written, and do not repeat or shorten their steps here. The only thing sw-do itself writes is a note in the task's "Notes".
+
+Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-init with `--tasks`. Run commands from the project root.
+
+## Steps
+
+1. **Pick the task.**
+   - Id given: `node docs/.sw/sw.mjs check <ID>`, then read `docs/tasks/<ID>.md`.
+   - No id: `node docs/.sw/sw.mjs ready`, and let the user choose.
+   - New work without a task file: sw-plan step 1 ("New work") creates it; then continue here.
+
+   `check` may settle the route before any classifying:
+
+   | `check` says | Do |
+   | --- | --- |
+   | status `done` or `cancelled` | stop and ask what the user wants |
+   | status `in-progress`, or a plan with `status: approved` | sw-implement, nothing else |
+   | a draft plan | large route; sw-plan revises it |
+   | open deps | stop, as sw-implement's gate does. Do not plan around it unasked |
+
+2. **Classify** from the task file alone: no code, no plan file. Take the first row that matches, from the top.
+
+   | Class | The task file shows | Route |
+   | --- | --- | --- |
+   | large | any of: more than six "Done when" items; more than one area; a question left open in "Notes"; `review:` set; a new format, interface or migration other work will depend on | sw-plan, the user's approval, then sw-implement |
+   | small | all of: one area, three "Done when" items or fewer, nothing left open in its notes, the change confined to a few files | sw-implement directly; no plan, no note |
+   | medium | everything else: one area, four to six "Done when" items or more than a few files, nothing open | an "Approach" note in "Notes", then sw-implement |
+
+3. **Say the route** in one line before acting: `Route: <class> (<the rubric conditions that decided it>).` Do not wait for an answer.
+
+   **Override.** A route the user names wins over the rubric, whether in the invocation ("as small", "with a plan", "no plan") or at any later point. When the override lowers the class, record it in the task's "Notes" as `- Route: <class>, chosen by the user.`
+4. **Follow the route.**
+   - **Small:** follow sw-implement from its step 1.
+   - **Medium:** write one bullet into the task's "Notes", starting `- Approach (sw-do, <date>):`, three to five lines long: the order of the work, which "Done when" items belong together, the constraints the notes set, and how the result is checked. Its sources are the task file and the area guide, if `node docs/.sw/sw.mjs explain <ID>` names one. No planner, no code reading, no plan file, no log entry. Then follow sw-implement from its step 1; its gate accepts `plan: none` with this note.
+   - **Large:** follow sw-plan, which skips its own size test when called from here; it clarifies, dispatches the planner, gets the user's approval and records it. That approval is the one planned stop of sw-do. Plan approved: continue with sw-implement in the same run. Plan dropped: stop; the task stays `todo`.
+
+## Common mistakes
+
+- Restating, shortening or skipping steps of sw-plan or sw-implement. They are followed whole, as written.
+- Reading code or a plan file to classify. The rubric uses the task file only.
+- Asking the user to confirm the route. Say it and go on; the user interrupts if they disagree.
+- Treating the Approach note as a plan. `check` still says `plan: none`, and the note holds no steps or verification list.
+- Writing a long Approach note, or exploring the code to write it. Past five lines the task is large: use the large route.
+- Implementing after a plan that was not approved, or going on after the user dropped it.
+- Setting the task to `done` here. sw-implement does that, after sw-summarize has verified every item.

package/skills/sw-implement/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants to implement, build, execute, start or cont
 
 # sw-implement
 
-Runs one task. You keep the task's status true and judge the result. The work is done by subagents that start from a clean context, on the models set in sw-config: an implementer, and a reviewer when the task asks for one. You do not read the code or the plan: their reports are your input.
+Runs one task. You keep the task's status true and judge the result. The work is done by subagents that start from a clean context, on the models set in sw-config: an implementer, and a reviewer when the task asks for one. You do not read the code or the plan: their reports are your input. Before the task is closed you summarize it yourself, with a command run for every "Done when" item.
 
 That split is what keeps a task cheap. A long session sends its whole context again on every step; work done in a fresh context does not carry yours, and yours stays small because the work never enters it.
 
@@ -22,50 +22,71 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | `can start: n/a, status is in-progress` | this is a continuation; skip step 3 |
    | `can start: n/a, status is done` or `cancelled` | stop and ask what the user wants |
    | `plan: ... (draft, not approved)` | stop; the plan needs the user's approval (sw-plan) |
-   | `plan: none` | fine for a small task: one area, three "Done when" items or fewer, nothing open in its notes, a few files. For anything larger, recommend sw-plan first and let the user choose |
+   | `plan: none` | fine for a small task: one area, three "Done when" items or fewer, nothing open in its notes, a few files. Also fine when the task's "Notes" hold an `Approach (sw-do, ...)` note: sw-do chose the medium route. For anything else, recommend sw-plan first and let the user choose |
    | `review: required (...)` | remember it for step 7 |
+   | `can finish: no` and `summary: none` | expected before the work: the summary is written in step 8 |
 
 3. **Mark it started** before any work:
    - in the frontmatter of `docs/tasks/<ID>.md`, `status: in-progress` and `started:` today;
    - in `docs/log.md`, a new entry `## [date] task | <ID> started`, in the layout its last entries use;
    - `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
-4. **Checks that need the environment.** If the task has a plan, look for `needs:` in it: `grep -n 'needs:' docs/plans/<ID>-plan.md`. Each hit is a check that starts services or changes data. Ask the user which of them may run; without a yes, none.
-5. **Dispatch the implementer** (how: "Dispatching" below). Its prompt is the task id, the project root if it is not your working directory, and which `needs:` checks it may run. Do not paste the plan into the prompt; it reads the files.
+4. **Checks that need the environment.** A check needs the environment when it starts a service, needs a running stack or changes data. Keep one list of them, each `allowed` or `not allowed`; it holds for the implementer, the reviewer and your own summary.
+   - With a plan: each hit of `grep -n 'needs:' docs/plans/<ID>-plan.md` is such a check. Ask the user which may run; without a yes a check is `not allowed`.
+   - Without a plan the list starts empty; step 6 fills it.
+5. **Dispatch the implementer**: the first row under "Dispatching".
 6. **Judge the report.** Its `Requirements:` list must name every "Done when" item and every scope, state or constraint item of the task; compare it with the task file.
-   - `met` needs evidence: a command or test and its result. Re-run one verification command yourself when the evidence is vague.
+   - `met` needs evidence: a command or test and its result. You do not re-run it here; step 8 runs a command for every item.
+   - `built, not verified`: the item's only check needs the environment and was not allowed. Ask the user once, in one question, whether each such check not yet answered may run, and add the answers to the list. Then go on either way, with no new implementer: the reviewer and your summary run what is allowed, and a check that cannot run leaves its item `unverified` in the summary and the task `in-progress`.
+   - `differs`: the item could not be built as worded. That is the user's call: show it and ask.
+     - Accepted: rewrite that "Done when" item in the task file to what was built, and add to "Notes" `- Changed <date>, accepted by the user: item <n> was "<old wording>"; reason: <why>.` (`<n>`: its position under "Done when"). The reviewer and the summary then read one wording.
+     - Not accepted: a fix round whose entry is the item in the task's wording.
    - `not met`, or missing from the list: the task is not done.
-   - `differs`: the implementer built something other than what the task says. That is the user's call: show it and ask. Until they accept it, the item is not met.
-7. **Review, if the task requires it.** Only when every requirement is met or accepted: dispatch the reviewer with the task id, the files the implementer changed, and which `needs:` checks it may run.
+
+   A fix round's report marks each entry `fixed` or `not fixed`. A `not fixed` entry goes to the user with the implementer's reason. Unless they accept what stands, no review is spent on it: go to step 8.
+7. **Review, if the task requires it.** It starts when every requirement is `met`, `built, not verified` or accepted: the review row under "Dispatching".
    - `Verdict: pass`: go on. Pass `important` and `minor` findings to the user in your report; they do not block.
-   - `Verdict: changes needed`: dispatch the implementer again with the blocking findings, word for word, then the reviewer again with the files changed since. After two rounds that still end in `changes needed`, stop and put the findings to the user.
+   - `Verdict: changes needed`: a fix round with the blocking findings, then the review row again, with those findings under `Recheck:`; one that comes back `still open` is blocking. After two such rounds that still end in `changes needed`, stop and put the findings to the user.
    - Do not review the change yourself in place of the reviewer, and do not argue a blocking finding away. If you think a finding is wrong, say so to the user and let them decide.
-8. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.
+8. **Summarize.** Follow sw-summarize for the task, yourself, in this session: it runs one command per "Done when" item, writes the `## Summary` section into the task file and appends the `summary` log entry. This step is not optional and is not delegated to the implementer. Run it whenever the implementer's work is in, also when an item is not met: the summary then records what is open. It does not set the status; step 9 does.
+9. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.
 
-   | Outcome | Task file | Log entry |
+   | Outcome | Task file | Log entry, after the `summary` entry |
    | --- | --- | --- |
-   | Every requirement met or accepted, review passed where required, and `check <ID>` says `can finish: yes` | `status: done`, `finished:` today | `task \| <ID> done`, then one body line on what was verified and, where it ran, the review verdict |
-   | Requirements met but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
-   | Anything not met, unverified, not reviewed or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
-
-9. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
-   - A guide exists: add the reports' `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
-   - No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
-10. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
+   | No requirement `not met`, every `differs` item accepted, review passed where required, and `check <ID>` says `can finish: yes` (every item in the summary is `verified`) | `status: done`, `finished:` today | `task \| <ID> done`, then one body line with the summary's count and, where it ran, the review verdict |
+   | Requirements met and verified but soft deps open | stays `in-progress` | `task \| <ID> waiting on <ids>` |
+   | The summary holds an `unverified` or `failed` item | stays `in-progress`; add to "Notes" what each open item needs | `task \| <ID> blocked: <n> unverified, <m> failed` |
+   | Anything else not met, not reviewed or awaiting the user's call | stays `in-progress`; add what is left to "Notes" | `task \| <ID> blocked: <reason>` |
+
+10. **Keep the area guide, if the area has one.** `node docs/.sw/sw.mjs explain <ID>` prints `area guide:` with a path or `none`.
+    - A guide exists: add the reports' `Guide:` lines to it, one line per fact under Layout, Patterns, Verify or Gotchas. Replace a line the new fact corrects, and keep the page under 60 lines.
+    - No guide: do nothing. A guide is worth starting once several tasks in an area have needed the same facts; if the user asks for one, create `docs/wiki/guide-<area, lowercase>.md` from `docs/.sw/templates/guide.md` and list it in `index.md`.
+11. **File what else was learned.** These are separate offers: act on each only when the user says yes to that one.
     - A report held a decision or constraint the wiki should keep: offer a wiki page (`type: decision` or `concept`), added to `index.md`.
     - The task fixed a problem whose cause is now known, or the review caught a defect worth remembering: offer a `type: lesson` page (Symptom, Cause, Fix, How to notice it earlier); sw-triage finds these later.
     - A report named follow-up work, or the review left `important` findings open: offer to create the tasks. A finding that lives only in the log is forgotten.
-11. **Report** to the user, in this order. Commit only if the user asks.
+12. **Report** to the user, in this order. Commit only if the user asks.
     - the outcome;
-    - each requirement with its evidence, and anything that differs from the task;
-    - the review verdict and its findings;
-    - the files changed;
+    - what was planned, and what was built with each deviation from the plan, as the Summary's Plan and Implementation parts say it;
+    - each "Done when" item with its verdict and command, taken from the Summary, and each item rewritten after an accepted difference, with its old wording;
+    - the review verdict and its findings, and the implementer's open decisions;
+    - the files changed, as the Summary lists them;
     - the tasks this unblocked (`node docs/.sw/sw.mjs ready`);
     - what the task cost: run `node docs/.sw/sw.mjs stats` and show its table as printed;
     - one last line: the task is recorded, so the next task is cheapest in a new session.
 
 ## Dispatching
 
-The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-reviewer` with `reviewer.md`, model from `models.implement` or `models.review`.
+What each dispatch gets:
+
+| Dispatch | Goes to | Prompt |
+| --- | --- | --- |
+| implementer | a fresh implementer | `<ID>`; `Checks:` |
+| fix round | the implementer that did the work where the tool can continue it (a further message to that agent), otherwise a fresh one | first line `Fix round for <ID>:`, then each entry word for word; `Checks:` |
+| review | a fresh reviewer, every time | `<ID>`; `Files:`, every file the task has changed (the implementer's list plus each fix round's); `Checks:`; from the second review on `Recheck:`, the previous review's blocking findings word for word |
+
+`Checks:` is the list of step 4, one line per check, `- <check>: allowed` or `- <check>: not allowed`; leave the block out while the list is empty. Every prompt names the project root if it is not your working directory.
+
+How to dispatch is the same for both roles: `sw-implementer` with `implementer.md`, `sw-reviewer` with `reviewer.md`, model from `models.implement` or `models.review`.
 
 | Tool | How |
 | --- | --- |
@@ -76,11 +97,8 @@ The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-re
 
 ## Common mistakes
 
-- Marking `done` because the implementer said so. Done means every requirement has evidence.
+- Marking `done`, or writing `verified`, from the implementer's report. The report is a claim; the check is the summary's commands, run in this session.
 - Accepting a `differs` item on the user's behalf. A sensible alternative is still not what the task asked for.
-- Skipping the review on a task that requires it, or doing it yourself in the same context that judged the implementation.
-- Starting work before the task file says `in-progress`. If the session dies, nobody knows the task was touched.
-- Letting a subagent edit the task file, the log or the task list. One writer for status: you.
-- Editing the task list in `index.md` by hand. It is written from the task files; change the task file and run `board`.
-- Reading the plan or the code "to follow along". The subagents already paid for that.
-- Running the next task in the same session out of momentum.
+- Giving a later review only the files the fix touched. A finding in an untouched file is then never rechecked.
+- Letting a subagent edit the task file, the log or the task list. One writer for status and for the summary: you.
+- Reading the plan or the code "to follow along". The subagents already paid for that; the summary reads only the plan's approach and verification.

package/skills/sw-init/SKILL.md

@@ -16,12 +16,14 @@ The vault is always `<project root>/docs`. Run every command below from the proj
 3. **Ask the user, in one message** (new vault only):
    - Task module on or off. Recommend on when the project is mainly code, off for a pure knowledge base.
    - If on, the area prefixes for task ids (`M-01`, `B-01`). Recommend the single default area `T` unless the project already has separately named parts. Area names are optional labels; do not ask for them separately.
-4. **Run the script**, with the flags that match the answer:
+   - Whether the Superwiki skills should also be kept in the repository, and for which agents: Claude Code (`.claude/skills`), Codex and Copilot (`.agents/skills`). Recommend yes when cloud agents will work on the repository (Claude Code on the web, Codex cloud, the Copilot coding agent): they start from a clone, see no home folder, and so have only the skills that are committed. Otherwise recommend no. Leave this question out when `<skill-dir>` is inside the project: the skills are in the repository already.
+4. **Run the script**, with the flags that match the answers. `--skills` takes the agents, comma-separated: `claude`, `codex`, `copilot` or `all`. Without it no skills are copied.
 
    ```bash
    node <skill-dir>/scripts/init.mjs --tasks                               # tasks on, default area T
    node <skill-dir>/scripts/init.mjs --tasks --areas "M=Mobile,B=Backend"  # tasks on, named areas
    node <skill-dir>/scripts/init.mjs --no-tasks                            # wiki only
+   node <skill-dir>/scripts/init.mjs --tasks --skills claude,codex         # tasks on, skills in the repository for Claude Code and Codex
    node <skill-dir>/scripts/init.mjs                                       # upgrade
    ```
 
@@ -31,9 +33,12 @@ The vault is always `<project root>/docs`. Run every command below from the proj
    | Status | Say |
    |---|---|
    | `created`, `updated` | what is new or changed |
+   | `created`, `updated` for `.claude/skills/sw-*/` or `.agents/skills/sw-*/` | that the skills are in the repository, in one sentence naming the folder, not one line per skill; and that the folder has to be committed before a clone or a cloud agent has them |
    | `kept`, `unchanged` | that user content and settings were not touched (one sentence, no list) |
+   | `kept ... (not installed by Superwiki)` | that a skill folder of that name was already there and was left as it is; name it. `npx superwiki install --project . --force <targets>` replaces it, if the user wants that |
    | `missing` | that this Superwiki build lacks the file; name it, and do not point the user at it |
    | `note` about `CLAUDE.md` | offer to add the `@AGENTS.md` line. Add it only after the user agrees to that specific change |
+   | `note` "skills in the repository left alone" | that the script ran from the repository's own copy of the skills and so did not update them; give the command from the note |
    | "docs/ already had content" | that content is untouched and outside the vault; sw-migrate converts it |
 
    End with how to look at the result: open `docs/` as an Obsidian vault, or open `docs/viewer.html` in Chrome or Edge and pick the project folder (only if the viewer was not reported `missing`).
@@ -45,7 +50,8 @@ The vault is always `<project root>/docs`. Run every command below from the proj
 | `docs/index.md`, `docs/log.md`, everything in `raw/`, `wiki/`, `tasks/`, `plans/` | kept |
 | `docs/.sw/sw.mjs`, `docs/.sw/templates/`, `docs/viewer.html` | replaced with this version |
 | `AGENTS.md` | only the Superwiki block (from the `sw:start` comment to the `sw:end` comment) is replaced |
-| `docs/.sw/config.json` | areas and models kept unless new flags are passed |
+| `docs/.sw/config.json` | areas, models and the agents whose skills are kept in the repository (`skills`) stay as saved unless new flags are passed |
+| `.claude/skills/sw-*/`, `.agents/skills/sw-*/`, when `skills` names an agent | a folder Superwiki installed is replaced with this version; any other folder of that name is kept. Nothing is deleted, also not after `--no-skills`. Left alone when the script runs from one of these folders |
 
 ## Without Node
 

package/skills/sw-init/assets/agents-block.md

@@ -31,7 +31,7 @@ Wiki:
 
 Tasks:
 
-- A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met: `status: done` and `finished:`. Each change of status gets a `task` entry in `log.md`.
+- A task's status lives only in its frontmatter. Before you start: `status: in-progress` and `started:`. When its "Done when" list is met and `sw-summarize` has verified it: `status: done` and `finished:`. Each change of status gets a `task` entry in `log.md`, each summary a `summary` entry.
 - The task list in `index.md` is written from the task files. After you add a task or change a task's status, title, milestone or dependencies, run `node docs/.sw/sw.mjs board`. Never edit that list by hand.
 - Do not start a task while any of its `deps` is not done.
 - If `explain <ID>` names an area guide (`docs/wiki/guide-<area>.md`), read it before you change code for the task: where things are, patterns, how to verify. Afterwards add the facts it was missing, one line each.
@@ -44,6 +44,9 @@ Skills. Use these without being asked. For work in this vault they come before a
 {{#tasks}}
 - Planning a task, or the user asks what to work on next: `sw-plan`.
 - Implementing a task: `sw-implement`. A change that needs no plan and touches one or two files may be done directly, under the task rules above.
+- One task from start to done in one command (it decides whether a plan is needed): `sw-do`.
+- Closing a task, or the user asks what a task did and how it was verified: `sw-summarize`.
+- Several tasks in a row without the user at each step: `sw-run`.
 - A question about a task (what, why, what it blocks): `sw-explain`.
 {{/tasks}}
 - A bug, failure or unexpected behavior is reported: `sw-triage` first, before any debugging.

package/skills/sw-init/assets/sw.mjs

@@ -79,6 +79,54 @@ export function extractWikilinks(body) {
   return out;
 }
 
+// ---------- Closing summary ----------
+// The `## Summary` section sw-summarize writes into a task file when the task is closed. Its
+// "Verification" list holds one numbered entry per "Done when" item: `1. **verified**: ...`.
+const VERDICT_ENTRY = /^(\d+)\.\s+\*\*(verified|failed|unverified)\*\*/;
+
+// Line ranges [start, end) of a body's `## ` sections, by heading text. Fenced code is skipped.
+function levelTwoSections(lines) {
+  const out = [];
+  let fenced = false;
+  lines.forEach((line, i) => {
+    if (/^\s*(```|~~~)/.test(line)) { fenced = !fenced; return; }
+    if (fenced) return;
+    const m = /^## +(.*?)\s*$/.exec(line);
+    if (!m) return;
+    if (out.length) out[out.length - 1].end = i;
+    out.push({ title: m[1].toLowerCase(), start: i, end: lines.length });
+  });
+  return out;
+}
+
+// null when the body has no `## Summary`. Otherwise the verdict counts over the "Done when" items
+// (an item without an entry is unverified), `complete` when every item is verified, the section's
+// markdown without its heading (`text`) and the body without the section (`rest`).
+export function closingSummary(body) {
+  const lines = String(body ?? '').split(/\r?\n/);
+  const sections = levelTwoSections(lines);
+  const section = sections.find(s => s.title === 'summary');
+  if (!section) return null;
+  const doneWhen = sections.find(s => s.title === 'done when');
+  const items = doneWhen ? lines.slice(doneWhen.start + 1, doneWhen.end).filter(l => /^[-*+]\s+\S/.test(l)).length : 0;
+  const inside = lines.slice(section.start + 1, section.end);
+  const entries = new Map();
+  for (const line of inside) {
+    const m = VERDICT_ENTRY.exec(line);
+    if (m && !entries.has(Number(m[1]))) entries.set(Number(m[1]), m[2]);
+  }
+  const counts = { verified: 0, unverified: 0, failed: 0 };
+  if (items) for (let n = 1; n <= items; n++) counts[entries.get(n) ?? 'unverified']++;
+  else for (const verdict of entries.values()) counts[verdict]++;
+  return {
+    items,
+    ...counts,
+    complete: entries.size > 0 && counts.unverified === 0 && counts.failed === 0,
+    text: inside.join('\n').trim(),
+    rest: [...lines.slice(0, section.start), ...lines.slice(section.end)].join('\n').trim(),
+  };
+}
+
 // ---------- Vault ----------
 const key = name => String(name).toLowerCase();
 const areaOf = id => (String(id).includes('-') ? String(id).slice(0, String(id).lastIndexOf('-')) : '');
@@ -123,6 +171,8 @@ export function buildVault(files) {
       started: d.started || '', finished: d.finished || '',
       // Any value asks for a separate review before the task may be done; the value names the kind.
       review: d.review ? String(d.review) : '',
+      // The closing summary's verdicts, or null while the task file has no `## Summary`.
+      summary: closingSummary(p.body),
       state: null, wave: 0, dependents: [], plan: null,
     });
   }
@@ -237,6 +287,8 @@ export function lint(vault) {
     const softOpen = t.openSoftDeps.filter(id => taskOf(vault, id));
     if (t.status === 'in-progress' && hardOpen.length) add('error', 'started-before-deps', path, `in-progress but not done: ${hardOpen.join(', ')}`);
     if (t.status === 'done' && (hardOpen.length || softOpen.length)) add('error', 'done-before-deps', path, `done but not done: ${[...hardOpen, ...softOpen].join(', ')}`);
+    // A done task without a summary predates the gate and is fine; a summary that is there must hold.
+    if (t.status === 'done' && t.summary && !t.summary.complete) add('error', 'done-unverified', path, `done but summary has ${t.summary.unverified} unverified, ${t.summary.failed} failed`);
     if ((t.status === 'in-progress' || t.status === 'done') && !t.started) add('warn', 'missing-date', path, '`started` is empty');
     if (t.status === 'done' && !t.finished) add('warn', 'missing-date', path, '`finished` is empty');
   }
@@ -1084,7 +1136,10 @@ function check(ctx) {
   if (t.error) return { error: t.error };
   const openSoftDeps = t.openSoftDeps.filter(id => taskOf(ctx.vault, id));
   const canStart = t.status === 'todo' && !t.openDeps.length;
-  const canFinish = !t.openDeps.length && !t.openSoftDeps.length;
+  // Finishing needs a closing summary in which every "Done when" item is verified (sw-summarize).
+  const canFinish = !t.openDeps.length && !t.openSoftDeps.length && !!t.summary?.complete;
+  const closing = t.summary && { items: t.summary.items, verified: t.summary.verified, unverified: t.summary.unverified, failed: t.summary.failed, complete: t.summary.complete };
+  const verdicts = closing && ['verified', 'unverified', 'failed'].filter(verdict => closing[verdict]).map(verdict => `${closing[verdict]} ${verdict}`).join(', ');
   const plan = t.plan ? `docs/${t.plan.path}` : null;
   const openDeps = t.openDeps.length ? `  open deps: ${t.openDeps.join(', ')}` : '';
   const startLine = t.status === 'todo'
@@ -1092,11 +1147,12 @@ function check(ctx) {
     : `can start: n/a, status is ${t.status}${openDeps}`;
   const draft = t.plan?.data.status === 'draft' ? '  (draft, not approved)' : '';
   return {
-    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan, review: t.review || null },
+    data: { id: t.id, status: t.status, canStart, canFinish, openDeps: t.openDeps, openSoftDeps, plan, review: t.review || null, summary: closing },
     text: [
       `${t.id}  ${t.status}  ${t.title}`,
       startLine,
       `can finish: ${canFinish ? 'yes' : 'no'}${openSoftDeps.length ? `  open soft deps: ${openSoftDeps.join(', ')}` : ''}`,
+      `summary: ${closing ? verdicts || 'no entries' : 'none'}`,
       `plan: ${plan ? plan + draft : 'none'}`,
       `review: ${t.review ? `required (${t.review})` : 'not required'}`,
     ].join('\n'),

package/skills/sw-init/assets/templates/task.md

@@ -32,6 +32,13 @@ status: todo | in-progress | done | cancelled. Cancelled tasks stay; ids are nev
 deps: must be done before this starts. soft_deps: may start, cannot finish before them.
 review: leave empty for no separate review. Any value (for example `required`, or the name of
 the project's review class) makes sw-implement run a reviewer before the task can be done.
-Keep this file short: steps go in docs/plans/<id>-plan.md, what happened goes in docs/log.md.
+A last section, "## Summary", is added by sw-summarize when the task is closed; do not write it
+by hand. It has four parts: "### Plan" (the approach as planned), "### Implementation" (what was
+built, deviations), "### Changes" (files, taken from git) and "### Verification", a numbered list
+with one entry per "Done when" item, each starting with a bold verdict (verified, unverified or
+failed) followed by the command and its result. A task can be `done` only when every item is
+verified.
+Keep this file short, the summary aside: steps go in docs/plans/<id>-plan.md, what happened
+goes in docs/log.md.
 Delete this comment.
 -->