superwiki 0.1.5 → 0.1.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sw",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "license": "MIT",
   "keywords": [
     "wiki",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sw",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "An LLM-maintained wiki and task tracker in docs/ for coding agents. Obsidian friendly, with a static viewer.",
   "license": "MIT",
   "skills": "./skills/",

package/README.md

@@ -29,7 +29,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 | | Before | After |
 | --- | --- | --- |
-| Read at the start of every session | 197 KB index | 94-byte catalog + 2.7 KB of rules |
+| Read at the start of every session | 197 KB index | 7.7 KB index (the 97 open tasks, a line each) + 2.7 KB of rules |
 | Read to start one task | the index, then the task's section | one file, 2 KB at the median |
 | Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
 
@@ -39,7 +39,7 @@ Measured on a real project with 165 tasks, converted from a single markdown inde
 
 ```text
 docs/
-  index.md       catalog of the wiki, one line per page
+  index.md       the open tasks, then the catalog of the wiki, one line per page
   log.md         append-only history
   raw/           your sources, never modified
   wiki/          pages the agent writes
@@ -50,6 +50,31 @@ docs/
 
 `AGENTS.md` gets a short block of rules so the agent maintains the vault in every session, with or without a command.
 
+You can follow the work without the viewer: `index.md` opens with the task list, written from the task files. Each open task is a line that links to its file; finished ones are listed by id.
+
+```markdown
+## Tasks
+
+ready 9 · in progress 1 · blocked 18 · done 20
+
+**In progress**
+
+- [[B-20]] Portfolio sync · M5
+
+**Ready**
+
+- [[F-01]] Frontend skeleton and guards · M0
+- [[B-18]] Valuation · M4
+
+**Blocked**
+
+- [[B-21]] Journal and thesis gates · M5 · waits on B-20
+
+**Done (20)** [[B-01]] [[B-02]] [[B-03]] ...
+```
+
+A task's status still lives only in its own file. The list is a view: the agent rewrites it with `sw.mjs board` whenever a task changes, and `lint` says when it has fallen behind.
+
 ## Install
 
 Requires Node 18 or newer.
@@ -263,7 +288,8 @@ node docs/.sw/sw.mjs check P-15             # can it start or finish, what is op
 node docs/.sw/sw.mjs explain P-15           # dependencies, what it unblocks, plan, area guide
 node docs/.sw/sw.mjs search sync timeout    # where something is mentioned
 node docs/.sw/sw.mjs next-id P              # next free id in an area
-node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors
+node docs/.sw/sw.mjs board                  # rewrite the task list in index.md from the task files
+node docs/.sw/sw.mjs lint                   # broken links, bad frontmatter, dependency errors, a stale task list
 node docs/.sw/sw.mjs stats                  # tokens, context and steps of the agent session here
 node docs/.sw/sw.mjs doctor                 # what that session carried before it read anything
 node docs/.sw/sw.mjs serve --open           # the viewer, reading files live
@@ -281,6 +307,7 @@ Edit sources in `src/`:
 | File | What it is |
 | --- | --- |
 | `src/core.js` | the vault model, derived task state, lint and search; shared by the CLI and the viewer |
+| `src/board.js` | the task list in `index.md` |
 | `src/sessions.js` | finds the record an agent keeps of a session |
 | `src/stats.js` | reduces a session record to cost per agent |
 | `src/doctor.js` | reduces a session record to what the session started with |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superwiki",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Agent skills that turn docs/ into an LLM-maintained wiki and task tracker. Obsidian-friendly. Works with Claude Code, Codex and Copilot CLI.",
   "keywords": [
     "claude-code",

package/skills/sw-implement/SKILL.md

@@ -25,7 +25,10 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    | `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 |
    | `review: required (...)` | remember it for step 7 |
 
-3. **Mark it started** before any work: in the frontmatter of `docs/tasks/<ID>.md` set `status: in-progress` and `started:` today. Append `## [date] task | <ID> started` to `docs/log.md`, in the layout its last entries use.
+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.
 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.
@@ -36,7 +39,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
    - `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.
    - 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.**
+8. **Record the outcome**, then run `node docs/.sw/sw.mjs board`.
 
    | Outcome | Task file | Log entry |
    | --- | --- | --- |
@@ -50,7 +53,7 @@ Run commands from the project root. `<skill-dir>` is the directory this SKILL.md
 10. **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: offer to create the tasks.
+    - 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.
     - the outcome;
     - each requirement with its evidence, and anything that differs from the task;
@@ -77,6 +80,7 @@ The same table serves both roles: `sw-implementer` with `implementer.md`, `sw-re
 - 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 or the log. One writer for status: you.
+- 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.

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

@@ -3,7 +3,12 @@
 
 `docs/` is a wiki you write and keep current, and an Obsidian vault the user reads.
 
+{{#tasks}}
+- `docs/index.md`: the open tasks, then the catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
+{{^tasks}}
 - `docs/index.md`: catalog, one line per wiki page. Read it first, then open only the pages you need.
+{{/tasks}}
 - `docs/log.md`: append-only. Add `## [YYYY-MM-DD] <kind> | <title>` at the end; read it with `tail`, never whole.
 - `docs/raw/`: sources. Read, never modify.
 - `docs/wiki/`: flat, one page per topic, frontmatter `type:` and one-line `summary:`.
@@ -27,6 +32,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`.
+- 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.
 - Work that belongs to no task (a quick fix, a small request) needs no task file. Append one `change` entry to `log.md` instead: what changed and why, in a line.

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Generated by scripts/build.mjs from src/core.js, src/sessions.js, src/stats.js, src/doctor.js, src/cli.js. Do not edit.
+// Generated by scripts/build.mjs from src/core.js, src/board.js, src/sessions.js, src/stats.js, src/doctor.js, src/cli.js. Do not edit.
 import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve as resolvePath, sep } from 'node:path';
@@ -322,6 +322,75 @@ export function guideFor(vault, area) {
   return vault.pages.find(p => p.folder === 'wiki' && p.data.type === 'guide' && key(p.data.area ?? '') === key(area)) || null;
 }
 
+// The task board: the open tasks as a section of index.md, so a person can follow the work in the
+// vault itself, without the viewer. It is a view, written from the task files by `sw.mjs board`
+// and never edited by hand; a task's status still lives only in its own frontmatter.
+// Open tasks get a line each. Finished ones are listed by id only, so the section stays small as
+// a project grows: index.md is the one file every session reads.
+
+const BOARD_START = '<!-- sw:board:start (written by `sw.mjs board`; do not edit) -->';
+const BOARD_END = '<!-- sw:board:end -->';
+const BOARD_BLOCK = /<!-- sw:board:start[^\n]*-->\n[\s\S]*?<!-- sw:board:end -->/;
+const REFRESH = 'run `node docs/.sw/sw.mjs board`';
+
+// Sections in reading order: what is being worked on, what can start, what waits.
+const OPEN_STATES = [['progress', 'In progress'], ['ready', 'Ready'], ['blocked', 'Blocked']];
+
+function openLine(vault, task) {
+  // A dependency that does not exist is lint's finding, not something a task waits on.
+  const waiting = task.openDeps.filter(id => taskOf(vault, id));
+  return [
+    `- [[${task.id}]] ${task.title}`,
+    ...(task.milestone ? [task.milestone] : []),
+    ...(task.state === 'blocked' && waiting.length ? [`waits on ${waiting.join(', ')}`] : []),
+  ].join(' · ');
+}
+
+// The board for this vault, markers included.
+export function taskBoard(vault) {
+  const { total } = summary(vault);
+  const counts = [
+    `ready ${total.ready}`, `in progress ${total.progress}`, `blocked ${total.blocked}`, `done ${total.done}`,
+    ...(total.cancelled ? [`cancelled ${total.cancelled}`] : []),
+  ];
+  const sections = OPEN_STATES
+    .map(([state, heading]) => [heading, tasksIn(vault, state)])
+    .filter(([, tasks]) => tasks.length)
+    .map(([heading, tasks]) => `**${heading}**\n\n${tasks.map(task => openLine(vault, task)).join('\n')}`);
+  // Finished tasks are looked up, not worked through: by id, not in running order.
+  const done = tasksIn(vault, 'done').map(task => task.id).sort((a, b) => a.localeCompare(b, 'en', { numeric: true })).map(id => `[[${id}]]`);
+  const paragraphs = [
+    '## Tasks',
+    total.total ? counts.join(' · ') : 'No tasks yet.',
+    ...sections,
+    ...(done.length ? [`**Done (${done.length})** ${done.join(' ')}`] : []),
+  ];
+  return `${BOARD_START}\n${paragraphs.join('\n\n')}\n${BOARD_END}`;
+}
+
+export const boardIn = indexText => (String(indexText).match(BOARD_BLOCK) || [null])[0];
+
+// index.md with this board in it: in place of the one it has, otherwise right under the title.
+export function indexWithBoard(indexText, board) {
+  const text = String(indexText);
+  if (BOARD_BLOCK.test(text)) return text.replace(BOARD_BLOCK, () => board);
+  const title = text.match(/^# .*\n?/);
+  if (!title) return `${board}\n\n${text}`;
+  const rest = text.slice(title[0].length).replace(/^\n+/, '');
+  return `${title[0].trimEnd()}\n\n${board}\n${rest ? `\n${rest}` : ''}`;
+}
+
+// A lint finding when index.md does not show the tasks as they are now, else null.
+export function boardFinding(vault) {
+  if (!vault.index) return null; // a missing index is reported on its own
+  const current = boardIn(vault.index.body);
+  if (!current && !vault.tasks.size) return null; // a vault without tasks needs no board
+  if (current === taskBoard(vault)) return null;
+  return current
+    ? { level: 'warn', code: 'stale-board', path: 'index.md', message: `the task list is out of date; ${REFRESH}` }
+    : { level: 'warn', code: 'missing-board', path: 'index.md', message: `the tasks are not listed; ${REFRESH}` };
+}
+
 // Finds the record an agent tool keeps of the session working in a project.
 // Claude Code, Codex and Copilot CLI each write every session to disk in their own layout; this
 // lists a project's sessions as { tool, id, modified, current, source } and picks one. What a
@@ -913,6 +982,7 @@ const HELP = `sw <command> [--docs <dir>] [--json]
   explain <ID>    a task's dependencies, what it blocks and unblocks, its plan and linked pages
   search <words>  pages and log entries that mention the words, best match first
   next-id <AREA>  next free task id for an area (numbers are never reused)
+  board           rewrite the task list in docs/index.md from the task files
   lint            structural checks; exit code 1 on errors
   stats           what the agent session here has cost so far: steps, context and tokens per agent
   doctor          what that session carried before it read anything: rule files, skill and tool lists
@@ -1128,8 +1198,25 @@ function nextIdCommand({ vault, args }) {
   return { data: { id }, text: id };
 }
 
+// The task list in index.md is a view of the task files; this writes it again from them.
+function boardCommand({ docs, vault }) {
+  if (!existsSync(join(docs, 'tasks'))) return { error: 'this vault has no task module (docs/tasks); sw-init --tasks adds it', code: 1 };
+  const path = join(docs, 'index.md');
+  if (!existsSync(path)) return { error: 'docs/index.md is missing; run sw-init', code: 1 };
+  const before = readFileSync(path, 'utf8');
+  const after = indexWithBoard(before, taskBoard(vault));
+  const changed = after !== before;
+  if (changed) writeFileSync(path, after);
+  const { total } = summary(vault);
+  return {
+    data: { changed, ready: total.ready, inProgress: total.progress, blocked: total.blocked, done: total.done },
+    text: `board: docs/index.md ${changed ? 'updated' : 'unchanged'}  ready ${total.ready}  in-progress ${total.progress}  blocked ${total.blocked}  done ${total.done}`,
+  };
+}
+
 function lintCommand({ vault }) {
-  const findings = lint(vault);
+  const board = boardFinding(vault);
+  const findings = [...lint(vault), ...(board ? [board] : [])];
   const errors = findings.filter(f => f.level === 'error').length;
   return {
     data: findings,
@@ -1272,6 +1359,7 @@ const COMMANDS = {
   explain: { run: explain, needsVault: true },
   search: { run: searchCommand, needsVault: true },
   'next-id': { run: nextIdCommand, needsVault: true },
+  board: { run: boardCommand, needsVault: true },
   lint: { run: lintCommand, needsVault: true },
   stats: { run: statsCommand, needsVault: false },
   doctor: { run: doctorCommand, needsVault: false },

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

@@ -1,6 +1,7 @@
 #!/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.
+import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -11,6 +12,7 @@ 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.
 const VAULT_ENTRIES = ['index.md', 'log.md', 'raw', 'wiki', 'tasks', 'plans', 'viewer.html'];
 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"]
 
@@ -116,7 +118,7 @@ function writeVault(docs, tasks, report) {
   }
 
   const today = new Date().toISOString().slice(0, 10);
-  report.keep(join(docs, 'index.md'), '# Index\n\nCatalog of the wiki: one line per page, `- [[file-name]]: summary`, grouped by type.\n');
+  report.keep(join(docs, 'index.md'), NEW_INDEX);
   report.keep(join(docs, 'log.md'), `# Log\n\nAppend-only. Entry format: \`## [YYYY-MM-DD] kind | title\`.\n\n## [${today}] init | Superwiki vault created\n`);
 
   // The viewer snapshot and the local server's address are per-machine and regenerated on demand.
@@ -128,6 +130,18 @@ function writeVault(docs, tasks, report) {
   }
 }
 
+// The task list in index.md is the one part of that file the tool owns. The vault's own CLI
+// writes it, so an upgraded vault gets the list in the format of the version just installed.
+function writeTaskBoard(docs, report) {
+  const index = join(docs, 'index.md');
+  const cli = join(docs, '.sw', 'sw.mjs');
+  if (!existsSync(cli)) return; // already reported as missing
+  const before = readFileSync(index, 'utf8');
+  const run = spawnSync(process.execPath, [cli, 'board', '--docs', docs], { encoding: 'utf8' });
+  if (run.status !== 0) return report.line('note', `the task list in docs/index.md was not written: ${run.stderr.trim()}`);
+  report.line(readFileSync(index, 'utf8') === before ? 'unchanged' : 'updated', 'docs/index.md (task list)');
+}
+
 function writeAgentRules(root, tasks, report) {
   const block = schemaBlock(tasks);
   const agentsPath = join(root, 'AGENTS.md');
@@ -174,6 +188,7 @@ function main(argv) {
   const hadTaskFiles = !previous && existsSync(join(docs, 'tasks'));
   const report = createReport(root);
   writeVault(docs, tasks, report);
+  if (tasks) writeTaskBoard(docs, report);
   const config = buildConfig(previous, { root, tasks, areas: options.areas });
   report.write(configPath, JSON.stringify(config, null, 2) + '\n');
   writeAgentRules(root, tasks, report);

package/skills/sw-lint/SKILL.md

@@ -17,6 +17,7 @@ Two passes. The first is a script and costs almost nothing. The second reads pag
 
    | Finding | Fix |
    |---|---|
+   | `stale-board`, `missing-board` | `node docs/.sw/sw.mjs board`: it rewrites the task list in `index.md` from the task files. Never edit that list by hand |
    | `not-in-index` | add `- [[page]]: summary` to `index.md`, using the page's `summary:` |
    | `missing-field` `summary` | copy it from the page's line in `index.md`; if there is none, read the page and write it |
    | `missing-field` `type` | read that page, write the field |

package/skills/sw-plan/SKILL.md

@@ -14,7 +14,10 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 1. **Pick the task.**
    - Id given: `node docs/.sw/sw.mjs check <ID>`, then read `docs/tasks/<ID>.md`. Status `done` or `cancelled`: stop and ask what the user wants. A plan already exists: this run revises it; say so. Open deps do not prevent planning.
    - No id, existing work: `node docs/.sw/sw.mjs ready`, and let the user choose.
-   - New work: agree on title, area and dependencies with the user, get the id from `node docs/.sw/sw.mjs next-id <AREA>`, and 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`.
+   - New work: agree on title, area and dependencies with the user, and get the id from `node docs/.sw/sw.mjs next-id <AREA>`. Then:
+     - 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.
 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.
@@ -36,7 +39,7 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
    - 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`.
+   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.
 
 ## Common mistakes
@@ -46,3 +49,4 @@ Needs the task module (`docs/tasks/`). If it is missing, say so and offer sw-ini
 - 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.
 - 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.