superwiki 0.1.6 → 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

@@ -0,0 +1,101 @@
+---
+name: sw-run
+description: Use when the user wants several Superwiki tasks worked through one after another without being asked at each step (run the backlog, do all tasks of an area, keep going until done or blocked, act as orchestrator), or invokes sw-run or sw:run.
+---
+
+# sw-run
+
+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**, 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 message does not answer it |
+   | --- | --- |
+   | 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. 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 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
+
+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 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 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 on a stop:
+
+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.

package/skills/sw-summarize/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: sw-summarize
+description: Use when a Superwiki task's work is finished and it has to be closed with evidence, when the user asks what a task did, what it changed or how it was verified, or invokes sw-summarize or sw:summarize with a task id. sw-implement runs it as the gate before `done`.
+---
+
+# sw-summarize
+
+Closes a task with a `## Summary` section in its task file: what was planned, what was built, what changed, and the evidence for each "Done when" item. `status: done` then means verified, and the task file says how.
+
+One rule carries the skill: **no verdict without a command run in this session.** Name the command that proves the item, run it now, read its exit code and its output, then write the verdict. An earlier run, the implementer's report, a passing test you remember, or "should pass" is not evidence.
+
+It runs in the session that invokes it: by hand as `sw-summarize <ID>`, or as a step of sw-implement. It is not handed to the implementer; the one who did the work does not also sign it off.
+
+Run commands from the project root.
+
+## Steps
+
+1. **Read the task**: `docs/tasks/<ID>.md`. Number its "Done when" items in the order they are written; the verification list uses the same numbers. If the task has a plan, read only its `## Approach` and `## Verification`.
+2. **Take the changes from git**, never from memory:
+   - uncommitted work: `git status --porcelain`;
+   - work already committed: `git log --name-status --format='%h %s' --grep='^<ID>:'`, the commits whose message starts with `<ID>:`;
+   - the short HEAD for the source line: `git rev-parse --short HEAD`.
+
+   List the files that belong to this task, without its bookkeeping (the task file, its plan, `docs/log.md`, `docs/index.md`, the area guide). Uncommitted work can sit next to other tasks' changes, so a file belongs to the task when it is both in `git status --porcelain` and in the "files changed" of this task's implementer reports, the first report and each fix round's. A session that ran several tasks holds other tasks' reports too; they do not count. Invoked by hand with no report in this session: the whole list, when the tree holds nothing else; otherwise ask the user which files belong to the task. No git repository, or the vault is ignored by git: say so in the section instead of listing files from recollection.
+3. **Pick one command per "Done when" item.**
+
+   | Where the command comes from | When |
+   | --- | --- |
+   | the plan's `## Verification` | the task has a plan |
+   | the commands the implementer reported | no plan, and a report is in this session |
+   | you choose it | otherwise, or the listed command does not prove the item |
+
+   A requirement about text (a document mentions something, a file exists, a format is described) is proven by `grep`, `test -f` or `lint`, not by having written the text. A requirement about behaviour (what a program, an endpoint or an agent following a prompt does) is proven by running the thing and observing it: run the program, call the endpoint, or dispatch a fresh agent on the scenario and read what it does. Finding the code or text that should cause the behaviour proves only that the text is there; without a run the item is `unverified`. A check needs the environment when it starts a service, needs a running stack or changes data. It runs only if the user allowed it: under sw-implement the answer is on that skill's list of such checks; when you summarize outside it, ask the user before you run one.
+4. **Run every command now and read the result.** Exit code first, then the line that shows the item holds: the test count, the matching line, the `0 errors`.
+
+   | What you have | Verdict |
+   | --- | --- |
+   | the command ran in this session, exited as expected, and its output shows the item | `verified` |
+   | the command ran and shows the item does not hold | `failed` |
+   | no command was run: a check that needs the environment and was not allowed, a difference from the item's wording that the user has not decided (run no command for it), nothing that can prove it, or only someone's word | `unverified`, with the reason |
+   | the command proves part of the item | `unverified`, saying which part is open |
+
+5. **Write the section** in the format below. It is the last section of the file. If the file already has a `## Summary`, replace it whole; every verdict in the new one comes from this session. Leave the frontmatter and the other sections as they are.
+6. **Log it**: append `## [date] summary | <ID> <verified> of <items> verified` to `docs/log.md`, in the layout its last entries use.
+7. **Ask the gate**: `node docs/.sw/sw.mjs check <ID>`. It prints `summary:` with the counts, and `can finish: yes` only when every item is verified and no dependency is open.
+8. **Close or hand back.**
+
+   | Invoked | Do |
+   | --- | --- |
+   | from sw-implement | return to its next step; it records the outcome, and its report shows the summary, so step 9 is skipped |
+   | by hand, and every item is verified, `check` says `can finish: yes`, and the task's `review:` is empty | set `status: done` and `finished:` today, append `## [date] task \| <ID> done` to the log, run `node docs/.sw/sw.mjs board` |
+   | by hand, and the task requires a review | write the summary only; the status stays. Say that sw-implement runs the review |
+   | by hand, and an item is unverified or failed | the status stays. Say what each open item needs |
+
+9. **Report**, when invoked by hand: show the user the summary itself, not only its counts. In this order: what was planned, what was built and each deviation, the files changed, the verdict for each item with its command, and whether the task can be closed. Say it in the language of the conversation; the section in the file stays as written.
+
+## The section
+
+```text
+## Summary
+
+Summarized <date>: <verified> of <items> verified.
+
+### Plan
+<the approach as planned, two to four lines>
+
+### Implementation
+<what was built; each deviation from the plan, or from the task's wording when there was no plan; or "No deviations.">
+
+### Changes
+- `path` (added | modified | deleted | renamed)
+
+Source: `git status --porcelain` at <short HEAD>, matched against the implementer's reports.
+
+### Verification
+1. **verified**: <"Done when" item 1>
+   - command: `<command>`
+   - result: <exit code and the line that shows it>
+2. **unverified**: <item 2>
+   - reason: <what it needs>
+3. **failed**: <item 3>
+   - command: `<command>`
+   - result: <exit code and the line that shows the failure>
+```
+
+- The four parts are always there, in this order.
+- A task that had no plan: the Plan part reads `No plan: implemented directly from the task.`, followed, when sw-do wrote an Approach note in "Notes", by that note in one or two lines.
+- An item rewritten after an accepted difference is a deviation, with or without a plan: name it under Implementation with its old wording, from the `- Changed <date>` line in the task's "Notes".
+- "Verification" is a numbered list with one entry per "Done when" item, numbered as the items are. Each entry starts with the verdict in bold: `verified`, `unverified` or `failed`. `check`, `lint` and the viewer read exactly that; an item without an entry counts as unverified.
+- The source line says how the files were picked. Changes taken from commits: name the commits instead of `git status --porcelain`. Picked without reports: `the whole tree` or `chosen by the user` in place of `matched against the implementer's reports`.
+- Keep the plan and implementation parts short. The section is a record, not a retelling of the log.
+
+## Common mistakes
+
+- Writing `verified` from the implementer's report. The report says where to look; the command you run says whether it is true.
+- One `npm test` as the evidence for every item. Each item gets the command that shows that item; a suite proves only what its tests cover.
+- "The file was written, so the item is met." Run the `grep` or `test -f`.
+- Closing a behavioural item with `grep`. The line exists; whether anything follows it is what the item asks.
+- Listing changed files from what you remember of the session. Git knows; ask it.
+- Softening a `failed` or `unverified` into `verified` with a note. A note does not open the gate; the verdict does.
+- Running a check that needs the environment and was not allowed, because the summary would otherwise stay incomplete. It stays incomplete, and the task stays open.
+- Setting `done` by hand on a task that requires a review.
+- Keeping parts of an old summary. Evidence from another session is not fresh.