superwiki 0.1.7 → 0.1.8

package/skills/sw-init/assets/viewer.html

@@ -452,6 +452,54 @@ 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`).
+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('-')) : '');
@@ -496,6 +544,8 @@ 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,
     });
   }
@@ -610,6 +660,8 @@ 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');
   }
@@ -1476,14 +1528,34 @@ function taskSections(t) {
       ${cell('Chain', `${up.size} ↑ · ${down.size} ↓`)}
     </div>
     ${callout}
+    ${t.summary ? `<div class="sec"><h4>Summary <span class="muted">${verdictCounts(t.summary)}</span></h4><div class="n-body n-summary"></div></div>` : ''}
     <div class="sec"><h4>Depends on <span class="muted">direct; open ▸ to follow the chain; dashed = soft</span></h4><div class="tree">${treeHtml(deps, 'deps')}</div></div>
     <div class="sec"><h4>Blocks <span class="muted">tasks waiting on this one</span></h4><div class="tree">${treeHtml(dependents, 'dependents')}</div></div>
-    <div class="sec"><h4>Details <span class="muted">${esc(t.page.path)}</span></h4><div class="n-body"></div></div>
+    <div class="sec"><h4>Details <span class="muted">${esc(t.page.path)}</span></h4><div class="n-body n-details"></div></div>
     ${linkedFrom(t.page)}`;
-  el.querySelector('.n-body').append(renderMd(t.page.body, t.page));
+  // The closing summary has its own section above, so "Details" shows the body without it.
+  if (t.summary) el.querySelector('.n-summary').append(badgeVerdicts(renderMd(t.summary.text, t.page)));
+  el.querySelector('.n-details').append(renderMd(t.summary ? t.summary.rest : t.page.body, t.page));
   return el;
 }
 
+// The closing summary's verdicts wear the status colours: verified as done, unverified as unknown, failed as blocked.
+const VERDICT_CLASS = { verified: 'st-done', unverified: 'st-unknown', failed: 'st-blocked' };
+
+function verdictCounts(s) {
+  return Object.keys(VERDICT_CLASS).filter(v => s[v]).map(v => `<span class="badge ${VERDICT_CLASS[v]}">${s[v]} ${v}</span>`).join(' ');
+}
+
+// In a rendered summary, the bold verdict that opens a numbered entry becomes a badge.
+function badgeVerdicts(root) {
+  for (const li of root.querySelectorAll('ol > li')) {
+    const strong = li.querySelector(':scope > strong:first-child, :scope > p:first-child > strong:first-child');
+    const cls = strong && VERDICT_CLASS[strong.textContent.trim()];
+    if (cls && !strong.previousSibling?.textContent.trim()) strong.classList.add('badge', cls);
+  }
+  return root;
+}
+
 function renderDrawer() {
   const page = pageByPath.get(ui.selected);
   if (!page) return;

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

@@ -1,12 +1,18 @@
 #!/usr/bin/env node
 // Scaffolds docs/ as a Superwiki vault. Safe to re-run: user content is kept, tool files are
-// replaced with this version, and the report says which was which.
+// replaced with this version, and the report says which was which. On request it also keeps a
+// copy of the Superwiki skills in the project, for agents that start from a clone.
 import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const ASSETS = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets');
+const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
+const ASSETS = join(SKILL_DIR, 'assets');
+// The folder of a project each agent reads skills from. Codex and Copilot share one.
+const SKILL_FOLDERS = { claude: '.claude/skills', codex: '.agents/skills', copilot: '.agents/skills' };
+// An empty file in a skill folder that Superwiki copied; the installer writes the same one.
+const INSTALLED_MARKER = '.sw-installed';
 const AREA_ID = /^[A-Za-z][A-Za-z0-9]*$/;
 const MANAGED_BLOCK = /<!-- sw:start[\s\S]*?<!-- sw:end -->/;
 // What a vault consists of at the top of docs/. Anything else there belongs to someone else.
@@ -15,18 +21,23 @@ const ROLES = ['plan', 'implement', 'review'];
 const NEW_INDEX = '# Index\n\n## Wiki\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n';
 
 const HELP = `init.mjs [--root <dir>] [--tasks | --no-tasks] [--areas "M=Mobile,B=Backend"]
+         [--skills claude,codex | --no-skills]
 
-  --root      project folder (default: current directory)
-  --tasks     add the task module (docs/tasks, docs/plans)
-  --no-tasks  wiki only
-  --areas     task id prefixes and their names (default: T=Tasks)
+  --root       project folder (default: current directory)
+  --tasks      add the task module (docs/tasks, docs/plans)
+  --no-tasks   wiki only
+  --areas      task id prefixes and their names (default: T=Tasks)
+  --skills     also keep the Superwiki skills in the project, for the agents named:
+               claude (.claude/skills), codex and copilot (.agents/skills), or all.
+               Commit those folders: agents that start from a clone have no home folder
+  --no-skills  stop keeping them in the project (the default; existing copies are not deleted)
 
-Run without --tasks or --no-tasks on an existing vault to upgrade it with its saved choices.`;
+Run without flags on an existing vault to upgrade it: the upgrade reuses the saved choices.`;
 
 class UsageError extends Error {}
 
 function parseArgs(argv) {
-  const options = { root: '.', tasks: null, areas: {}, help: false };
+  const options = { root: '.', tasks: null, areas: {}, skills: null, help: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--help') options.help = true;
@@ -34,11 +45,25 @@ function parseArgs(argv) {
     else if (arg === '--tasks') options.tasks = true;
     else if (arg === '--no-tasks') options.tasks = false;
     else if (arg === '--areas') options.areas = parseAreas(argv[++i] ?? '');
+    else if (arg === '--skills') options.skills = parseSkillAgents(argv[++i] ?? '');
+    else if (arg === '--no-skills') options.skills = [];
     else throw new UsageError(`unknown argument: ${arg}\n\n${HELP}`);
   }
   return options;
 }
 
+function parseSkillAgents(text) {
+  const known = Object.keys(SKILL_FOLDERS);
+  const agents = new Set();
+  for (const name of text.split(',').map(part => part.trim()).filter(Boolean)) {
+    if (name === 'all') known.forEach(agent => agents.add(agent));
+    else if (known.includes(name)) agents.add(name);
+    else throw new UsageError(`bad agent "${name}" in --skills: ${known.join(', ')} or all`);
+  }
+  if (!agents.size) throw new UsageError(`--skills needs at least one agent: ${known.join(', ')} or all`);
+  return [...agents];
+}
+
 function parseAreas(text) {
   const areas = {};
   for (const pair of text.split(',').map(part => part.trim()).filter(Boolean)) {
@@ -86,7 +111,8 @@ function readConfig(path) {
   return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
 }
 
-function buildConfig(previous, { root, tasks, areas }) {
+// `skills` lists the agents whose project folder holds a copy of the skills; [] means none.
+function buildConfig(previous, { root, tasks, areas, skills }) {
   const models = Object.fromEntries(ROLES.map(role => [role, previous?.models?.[role] ?? {}]));
   const chosenAreas = Object.keys(areas).length ? areas : previous?.areas ?? { T: 'Tasks' };
   return {
@@ -95,6 +121,7 @@ function buildConfig(previous, { root, tasks, areas }) {
     tasks,
     areas: tasks ? chosenAreas : {},
     models,
+    skills: skills ?? previous?.skills ?? [],
     ...(previous?.tools ? { tools: previous.tools } : {}),
   };
 }
@@ -165,6 +192,61 @@ function writeAgentRules(root, tasks, report) {
   }
 }
 
+// A name the config holds that this version does not know has no folder and is skipped.
+const skillFolders = agents => [...new Set(agents.map(agent => SKILL_FOLDERS[agent]).filter(Boolean))];
+const sameFolder = (a, b) => existsSync(a) && existsSync(b) && realpathSync(a) === realpathSync(b);
+
+// Every file under a folder, by its path relative to that folder.
+function filesIn(folder, prefix = '') {
+  const files = new Map();
+  for (const entry of readdirSync(folder, { withFileTypes: true })) {
+    const path = join(folder, entry.name);
+    const name = `${prefix}${entry.name}`;
+    if (entry.isDirectory()) for (const [inner, content] of filesIn(path, `${name}/`)) files.set(inner, content);
+    else files.set(name, readFileSync(path));
+  }
+  return files;
+}
+
+function sameSkill(source, copy) {
+  const expected = filesIn(source);
+  const found = filesIn(copy);
+  expected.delete(INSTALLED_MARKER);
+  found.delete(INSTALLED_MARKER);
+  return expected.size === found.size && [...expected].every(([name, content]) => found.get(name)?.equals(content));
+}
+
+// A copy of every sw-* skill that sits next to this one goes into the project folders the
+// chosen agents read. The source is the folder this script was installed into, so the copy needs
+// neither the installer nor the network and works the same from a plugin.
+function writeSkills(root, agents, report) {
+  const source = join(SKILL_DIR, '..');
+  if (Object.values(SKILL_FOLDERS).some(folder => sameFolder(source, join(root, folder)))) {
+    return report.line('note', 'skills in the repository left alone: init.mjs runs from the project\'s own copy; update them with "npx superwiki install --project . <targets>"');
+  }
+  const names = readdirSync(source).filter(name => name.startsWith('sw-') && existsSync(join(source, name, 'SKILL.md'))).sort();
+  for (const folder of skillFolders(agents)) {
+    mkdirSync(join(root, folder), { recursive: true });
+    for (const name of names) {
+      const from = join(source, name);
+      const to = join(root, folder, name);
+      const label = `${folder}/${name}/`;
+      const present = lstatSync(to, { throwIfNoEntry: false });
+      // Superwiki's own: a real folder carrying the marker. A link, or a folder without it, is someone else's.
+      if (present && !(present.isDirectory() && existsSync(join(to, INSTALLED_MARKER)))) {
+        report.line('kept', `${label} (not installed by Superwiki)`);
+      } else if (present && sameSkill(from, to)) {
+        report.line('unchanged', label);
+      } else {
+        if (present) rmSync(to, { recursive: true, force: true });
+        cpSync(from, to, { recursive: true });
+        writeFileSync(join(to, INSTALLED_MARKER), '');
+        report.line(present ? 'updated' : 'created', label);
+      }
+    }
+  }
+}
+
 // What was in docs/ before the first init and is not part of a vault.
 function foreignEntries(docs) {
   if (!existsSync(docs)) return [];
@@ -189,12 +271,14 @@ function main(argv) {
   const report = createReport(root);
   writeVault(docs, tasks, report);
   if (tasks) writeTaskBoard(docs, report);
-  const config = buildConfig(previous, { root, tasks, areas: options.areas });
+  const config = buildConfig(previous, { root, tasks, areas: options.areas, skills: options.skills });
   report.write(configPath, JSON.stringify(config, null, 2) + '\n');
   writeAgentRules(root, tasks, report);
+  if (config.skills.length) writeSkills(root, config.skills, report);
 
   console.log(report.lines.join('\n'));
-  console.log(`\nvault: docs/  tasks: ${tasks ? `on (areas: ${Object.keys(config.areas).join(', ')})` : 'off'}`);
+  const taskState = tasks ? `on (areas: ${Object.keys(config.areas).join(', ')})` : 'off';
+  console.log(`\nvault: docs/  tasks: ${taskState}  skills: ${skillFolders(config.skills).join(', ') || 'not in the repository'}`);
   if (foreign.length) {
     const shown = `${foreign.slice(0, 8).join(', ')}${foreign.length > 8 ? ', ...' : ''}`;
     // After sw-migrate the task files are already there; only a first init on old docs needs the hint.

package/skills/sw-lint/SKILL.md

@@ -28,6 +28,7 @@ Two passes. The first is a script and costs almost nothing. The second reads pag
    | Finding | Why it needs a human |
    |---|---|
    | `started-before-deps`, `done-before-deps`, `dep-cycle`, `cancelled-dep` | either the status or the dependency is wrong; only the user knows which |
+   | `done-unverified` | the task is `done` but its `## Summary` holds an unverified or failed item. Run sw-summarize for it; do not edit a verdict by hand |
    | `missing-date` you could not fill | no history to take it from, or it hangs on a finding above |
    | `duplicate-name` | one of the pages must be renamed and every link to it re-pointed |
    | `broken-link` with no clear target, `orphan-plan`, `unknown-dep` | the page may be missing or the reference stale |

package/skills/sw-plan/SKILL.md

@@ -18,9 +18,11 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
      - write `docs/tasks/<ID>.md` from `docs/.sw/templates/task.md` with `status: todo`, a "Goal" and a "Done when" list;
      - append `## [date] task | <ID> created` to `docs/log.md`;
      - run `node docs/.sw/sw.mjs board`, so the task list in `index.md` shows it.
-2. **Does it need a plan?** Judge from the task file alone. A task is small when all of these hold: one area, three "Done when" items or fewer, nothing left open in its notes, and the change it describes is confined to a few files. A small task needs no plan: say so and offer `sw-implement <ID>` directly. Go on with planning only if the user wants a plan anyway, or the task is not small.
+2. **Does it need a plan?** Judge from the task file alone. A task is small when all of these hold: one area, three "Done when" items or fewer, nothing left open in its notes, and the change it describes is confined to a few files. A small task needs no plan: say so and offer `sw-implement <ID>` directly. Go on with planning only if the user wants a plan anyway, or the task is not small. Called from sw-do: the route is already chosen; skip this step.
 3. **Clarify.** Ask the user only what the task file leaves open about scope or intent, one question at a time, each with your recommendation. Add the answers to the task's "Notes" now. Do not read code to find questions; the planner surfaces the technical ones. Skip this when nothing is open.
-4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and any feedback from an earlier round. It writes the plan file as a draft and returns a short message.
+4. **Dispatch the planner.** Its prompt is: the task id, today's date, the project root if it is not your working directory, and, from the second round on, what the user's reply changed: the answers that differ from the ones the plan assumed, the feedback, the ids of the tasks a split created, or `split declined`. It writes the plan file as a draft and returns a short message.
+
+   A second round goes to the planner that wrote the draft where the tool can continue it (a further message to that agent), otherwise to a fresh one.
 
    | Tool | How |
    | --- | --- |
@@ -29,24 +31,42 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
    | Copilot CLI | `task` tool with agent `sw-planner` |
    | No subagents available, or the agent is not defined | follow `planner.md` yourself, in this session, and tell the user the configured model was not used |
 
-5. **Get approval.** Show the user the planner's `Approach`, its `Questions` (each with the assumed answer as your recommendation) and its `Split`, and name the plan file so they can read it. Do not read the plan file into your own context unless the user asks you about its content. (Claude Code: enter plan mode with `EnterPlanMode` now and present through `ExitPlanMode`, if those tools are available; anywhere else, a normal message.)
-   - An answer differs from what the plan assumed, or the user wants changes: dispatch the planner again with the answers or feedback; it revises the file.
-   - The planner proposes a split: create the tasks (step 1, "New work") only when the user agrees.
-   - The user drops the plan: delete the draft file.
+5. **Present the plan and get approval.** Show the user, in a normal message, the planner's `Approach`, its `Questions` (each with the assumed answer as your recommendation), its `Split`, and the path of the plan file so they can read it. Plan mode is not used: a reply can need files written before the plan is shown again. Read the plan file into your own context only if the user asks you about its content.
+
+   Handle the reply in this order:
+   1. The user agrees to a split: carry it out first, as "An agreed split" below says.
+   2. An answer differs from the one the plan assumed, the user wants changes, or the user declines a split: dispatch the planner again (step 4) with all of it in one prompt, and with the ids of any tasks the split created. Then present the revised plan the same way and wait for the reply again.
+   3. The user accepts the plan as presented, with nothing left to change: that is the approval; go to step 6. A split agreed in the same reply needs no second round, since the plan already covers only the items that stay.
+   4. The user drops the plan: delete the draft file and stop. Tasks a split already created stay; say so.
+
+   Called from sw-do, every presentation up to the approval belongs to its one planned stop.
 6. **Record**, after approval:
-   - in the plan file, change `status: draft` to `status: approved`;
+   - in the plan file, change `status: draft` to `status: approved`: read only its frontmatter (the first lines, up to the closing `---`) and change that line with your edit tool;
    - in the task's "Notes", the answers given in step 5;
    - in the area guide, if `node docs/.sw/sw.mjs explain <ID>` names one, the planner's `Guide:` lines, one line per fact;
    - in `docs/log.md`, a new entry `## [date] plan | <ID>`, in the layout the log's last entries use.
 
    Then run `node docs/.sw/sw.mjs lint`. If it reports `stale-board`, a task's title, milestone or dependencies changed along the way: run `node docs/.sw/sw.mjs board`.
-7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it.
+7. **Stop.** Do not start implementing. Tell the user the plan is approved and that sw-implement `<ID>` runs it. Called from sw-do: return to it; it continues with sw-implement.
+
+## An agreed split
+
+The planner's `Split:` names, per new task, its title, its dependencies and the "Done when" items of `<ID>` it takes over. Once the user agrees:
+
+1. For each new task:
+   - its id from `node docs/.sw/sw.mjs next-id <AREA>`, where `<AREA>` is the id prefix of `<ID>` (`T` for `T-11`);
+   - `docs/tasks/<NEW>.md` from `docs/.sw/templates/task.md`, without the template's comment: `status: todo`; the title and `deps` the `Split:` line names; `review:`, `milestone:` and `priority:` copied from `<ID>`; `soft_deps:` empty; a "Goal" of one or two lines drawn from the items it takes over; under "Done when" those items, word for word; under "Sources" every link of `<ID>`'s "Sources"; in "Notes" `- Split from [[<ID>]] on <date>.`, then a copy of every note of `<ID>` and every answer the user gave in this round that bears on the moved items, so that the new task is later planned on them;
+   - in `docs/log.md`, `## [date] task | <NEW> created`.
+2. In `docs/tasks/<ID>.md`: remove the moved items from "Done when"; add to `deps` each new task the `Split:` line says `<ID>` must wait for; add to "Notes" `- Split <date>: "Done when" items <n, ...> moved to [[<NEW>]].`, numbered as the items stood before the split, one line per new task.
+3. Run `node docs/.sw/sw.mjs board`.
 
 ## Common mistakes
 
 - Planning a small task. The plan costs more than the work.
 - Exploring the codebase before dispatching, or reading the plan back. You pay for it twice.
 - Editing the plan yourself. If something in it is wrong, send it back to the planner.
-- Setting the task to `in-progress`. Planning does not change status.
+- Setting the task to `in-progress`. Planning does not change status; only sw-run marks a task started before planning it.
+- Creating the tasks of a proposed split before the user agrees to it.
+- Approving a revised plan the user has not been shown.
 - Planning several tasks in one plan file. One task, one plan; shared design goes to a `type: decision` wiki page that the plans link.
 - Adding the new task to the list in `index.md` by hand. `board` writes that list from the task files.

package/skills/sw-run/SKILL.md

@@ -5,82 +5,97 @@ description: Use when the user wants several Superwiki tasks worked through one
 
 # sw-run
 
-Works through tasks in order, unattended: for each one, plan it if it needs a plan, implement it, have it reviewed if it requires that, record it, and go on to the next. You are the orchestrator. Every piece of work goes to a subagent with a clean context; your session holds only the queue, the reports and the decisions.
-
-Each task is run exactly as sw-implement runs it. This skill adds what a run of many needs: answers agreed once at the start, decisions you make in the user's place and write down, and rules for when to stop.
+Works through tasks in order, unattended, each one as the single-task skills run it. You are the orchestrator: subagents with clean contexts do the work; your session holds the queue, the reports and the decisions.
 
 Run commands from the project root.
 
+## The skills a run follows
+
+Load each once and follow it for every task:
+
+- **sw-do**: step 1's `check` table, steps 2 and 3 (the rubric, the `Route:` line) and step 4's medium route (the Approach note);
+- **sw-plan**: steps 4 to 6 and "An agreed split", on the large route;
+- **sw-implement**: steps 2 to 10 and "Dispatching";
+- **sw-summarize**: all of it, as sw-implement step 8 calls it.
+
+This skill takes the place of their other steps.
+
 ## Before the first task
 
-1. **Scope.** Which tasks: an area, a list of ids, or everything that becomes ready. Take it from the user's message. Default order is the order of `node docs/.sw/sw.mjs ready`.
-2. **Standing answers.** The user will not be asked again, so these are settled now. Ask only for the ones their message leaves open, in one question:
+1. **Scope**, from the user's message: an area, a list of ids, or everything that becomes ready. An area is a task id prefix; `areas` in `docs/.sw/config.json` maps each prefix to its name, so "the backend area" is the prefix named Backend. Its tasks are the ids with that prefix that `node docs/.sw/sw.mjs ready` lists at the start, in its order; tasks that become ready later join only when the message asks for them. No prefix matches: ask, or, when questions are ruled out, stop and say so.
+2. **Standing answers**, settled now, since the user will not be asked again:
 
-   | Question | If the user does not say |
+   | Question | If the message does not answer it |
    | --- | --- |
-   | May plans be approved without them? | yes; that is what unattended means |
-   | Which `needs:` checks (starting services, changing data) may run? | none |
+   | May plans and proposed splits be approved without them? | yes |
+   | Which checks that start a service, need a running stack or change data may run? | none |
    | Commit after each task? Push? | no commit, no push |
    | Go on with other tasks when one stops? | no; stop the run |
 
+   A question is answered only where the message speaks to it: "finish them all" sets the scope and "don't ask me" rules out questions, and neither answers one; "don't commit" answers commit, not push. Ask for the open ones in one question. When the message rules out questions, ask nothing: write one line that starts `Standing answers:` and gives all four, the user's where given and the default otherwise, and start.
 3. **Check that the run can do what was agreed**, before any task is touched:
    - `node docs/.sw/sw.mjs lint`: errors are fixed or reported first.
-   - Commits were agreed: run one harmless git command. If the project's settings or the tool refuse git, say so now. Do not start a run whose terms cannot be met, and do not look for another way to run the refused command.
-   - The working tree holds changes that belong to no task of this run: say what they are and ask once whether to leave them or commit them first.
-4. **A clean session per task.** You cannot open a new session; a fresh subagent per role is the clean context. If the user asked for sessions, say this is how it is done.
+   - Commits were agreed: run one harmless git command. Refused by the project's settings or the tool: say so now, and neither start the run nor look for another way to run the command.
+   - Changes in the working tree that belong to no task of this run: say what they are and ask once whether to leave them or commit them first. Questions ruled out: leave them.
 
 ## Each task
 
-1. **Next task**: `node docs/.sw/sw.mjs ready`. A task in progress comes first, then the first ready task in scope. None left: go to "The report".
-2. **Run it as sw-implement does**: gate, mark it started, checks that need the environment, implementer, judge the report, review if required, record, task list. Load sw-implement once and follow it for every task. What differs in a run:
-
-   | In sw-implement or sw-plan | In a run |
-   | --- | --- |
-   | a task that is not small: "recommend sw-plan and let the user choose" | plan it. Mark the task started first, then dispatch the planner as sw-plan step 4 says |
-   | the planner's `Questions` go to the user | answer each with the planner's assumed answer, unless the task file, a wiki page or a recorded lesson says otherwise (`node docs/.sw/sw.mjs search <words>`). Write every answer into the task's "Notes" as `decided without the user: ...` |
-   | the plan waits for approval | approve it, if that was agreed, with a log entry that says it was approved under the run's standing answer |
-   | a `differs` item is the user's call | send it back to the implementer once with the task's wording. Still differs: stop |
-   | offers after a task (wiki pages, lessons, follow-up tasks) | do not ask and do not act. List them in the report |
-
-3. **Close the task.** Commit, if agreed: only the files this task changed, message `<ID>: <title>`. Push only if agreed. A refused commit or push stops the run.
-4. **Check your own size**: `node docs/.sw/sw.mjs stats`, row `main`. If its `peak` is above 200k tokens, stop here, between tasks: every further step would pay for all of it. Tell the user to start a new session and run sw-run again; the queue is in the files, so nothing is lost.
+1. **Next task**: `node docs/.sw/sw.mjs ready`. A task in scope that is in progress comes first, then the first ready one in scope. None left: go to "The report".
+2. **Gate**: sw-implement step 2, with sw-do's `check` table. A task whose plan is approved goes to step 5; one already in progress skips step 3.
+3. **Mark it started** (sw-implement step 3), before routing.
+4. **Route it** with sw-do's rubric, from the task file alone, and say its `Route:` line, as sw-do step 3 does. A draft plan means large.
+   - Small: step 5.
+   - Medium: the `Approach (sw-do, <date>):` note into "Notes", as sw-do writes it, unless one is there; then step 5.
+   - Large: sw-plan steps 4 to 6; step 6 runs whole, so the plan is `approved`.
+5. **Implement**: sw-implement steps 4 to 10, with the differences below. Step 10 keeps the area guide for every task.
+6. **Close the task**, also one that stops the run:
+   - `node docs/.sw/sw.mjs lint`. An error stops the run.
+   - Commit, if agreed and the task is `done`: the files under its Summary's `### Changes` plus its bookkeeping (task file, plan, `docs/log.md`, `docs/index.md`, the area guide if changed), message `<ID>: <title>`. Push only if agreed. A refused commit or push stops the run.
+7. **Check your own size**: `node docs/.sw/sw.mjs stats`, row `main`. A `peak` above 200k tokens stops the run here, between tasks.
+
+### What differs in a run
+
+| In the single-task skills | In a run |
+| --- | --- |
+| sw-implement step 2: a draft plan stops; a task that is not small and has no plan goes to the user | step 4's route decides |
+| sw-plan step 5: the user sees the plan, answers its questions, approves it and any split | nothing is presented. Each question gets the assumed answer, unless the task file, a wiki page or a lesson says otherwise (`sw.mjs search`); the plan and any split are approved under the standing answer. A split's new task joins the queue only if it is in scope |
+| sw-plan step 6: the answers go into "Notes"; the `plan` log entry | the answers go into "Notes" once, as decisions made without the user; the log entry gets the body line `Approved under the run's standing answer.` |
+| sw-implement steps 4 and 6: the user allows checks that need the environment | the standing answer, no question: unattended means fewer questions, not more permission |
+| sw-implement step 6: a `differs` item is the user's call | one fix round, its entry the item in the task's wording |
+| sw-implement steps 11 and 12: offers, and the report | offers, open decisions and open findings go into the run's report; the rest is in each task's Summary |
+
+### Decisions made without the user
+
+Every answer you give in the user's place, recorded where it was made:
+
+- on a task (a planner question answered, a plan or split approved, a `differs` item sent back): in its "Notes" as `- <date>, decided without the user: ...`, and in the report with its id;
+- for the run (each default in the `Standing answers:` line, working-tree changes left alone): in the report under `run` and nowhere else, even when it later decides something on a task, as a check not allowed does.
 
 ## When to stop
 
-Stop the run, leave the task `in-progress` with what is open in its "Notes", and report. Do not skip the task and take the next one unless that was agreed and the next task does not depend on it.
+A stop on a task fires once the task is closed (step 6), with its summary and outcome recorded; a summary with an `unverified` or `failed` item takes step 9's `blocked: <n> unverified, <m> failed` row. Then stop and report, also on the last task in scope. Take the next task instead only if agreed and independent of this one.
 
-- A requirement is `not met` or still `differs` after one more round with the implementer.
-- The review still says `changes needed` after two rounds.
-- The task cannot be verified without a `needs:` check that was not allowed.
-- A commit or push that was agreed is refused.
-- `lint` reports an error after the task was recorded.
-- Your `peak` is above 200k (this one is between tasks, with nothing left open).
+- A requirement is `not met`, or a fix round reports an entry `not fixed`. A `differs` item not fixed is a difference the user has not decided: `unverified` in the summary.
+- The review after the second fix round still says `changes needed`.
+- The summary leaves an item `failed` or `unverified`, also one whose check was not allowed: that stop too fires after the summary, never before the work, with the task built and reviewed where required.
+- `lint` reports an error, or an agreed commit or push is refused.
+- A large task, when plans may not be approved without the user: stop before its planner.
+- Your `peak` is above 200k.
 
 ## Keeping the run cheap
 
-A run pays for the orchestrator's context once per step, for every task. What keeps it small:
-
-- **A fresh subagent for every task and every role.** Never continue the agent that planned or implemented the previous task.
-- **Prompts as the role files ask**: task id, date, project root, the checks it may run, the standing answers that concern it. No reading lists and no project summary; each role knows what to read.
-- **Reports, not files.** Do not read code, plans or the other tasks' files. `ready`, `check` and `explain` answer what you need about the queue.
-- **One load of each skill.** Do not load a skill again to re-read it.
-- **Edit frontmatter with your edit tool**, not with `sed` or another text substitution: a pattern that does not match fails silently and the status is then wrong without an error.
+- **A fresh subagent for every task and role**, as the clean session a skill cannot open. Only a fix round continues one: the implementer of the same task.
+- **Prompts exactly as sw-plan step 4 and sw-implement's "Dispatching" give them.** No reading lists, no project summary, no word on commits: the role files say changes stay uncommitted and committing is yours.
+- **Reports, not files.** You read no code and no other task's files. Of a plan you read what sw-summarize reads, `## Approach` and `## Verification`, and its frontmatter when sw-plan step 6 approves it.
+- **Edit frontmatter with your edit tool**: a `sed` pattern that does not match fails silently.
 
 ## The report
 
-At the end, or when the run stops:
+At the end or on a stop:
 
-1. A table: task, outcome, review verdict, commit.
-2. **Decisions made without the user**, one line each with the task id. This is the list the user must read.
-3. What stopped the run, if it stopped, and what would let it continue.
-4. Offers and open findings collected along the way.
+1. A table, one row per task in scope (`not reached` for the rest): task, route, outcome, the last review verdict with the number of reviews, commit; `-` where none.
+2. **Decisions made without the user**, one line each with the task id, or `run`.
+3. What stopped the run, and what would let it continue: for a difference, the user's call on it, applied as sw-implement step 6 says; for a check not allowed, the user's yes; for a failed review, its blocking findings.
+4. Offers, open decisions, and every review's `important` and `minor` findings.
 5. `node docs/.sw/sw.mjs stats`, as printed.
-6. What is ready next.
-
-## Common mistakes
-
-- Asking the user mid-run something the standing answers cover, or not asking at the start something they do not.
-- Deciding a `needs:` check may run because the run is unattended. Unattended means fewer questions, not more permission.
-- Piling several tasks into one uncommitted tree after a commit was refused.
-- Running one long subagent that plans, implements and reviews a task. Measured on a real project, such an agent reached a context of almost a million tokens and sent over ten times what the three separate roles sent on another task of the same project.
-- Carrying on past 200k because the next task looks small.
+6. What is ready next.