rodo-spec 2.2.1 → 2.4.0

package/dist/index.js

@@ -11057,7 +11057,7 @@ function ensureBlock(path, block, kit20Hashes, importsAgents, dryRun = false) {
 // package.json
 var package_default = {
   name: "rodo-spec",
-  version: "2.2.1",
+  version: "2.4.0",
   description: "RODO method CLI \u2014 install the kit, manage cards, sync with the board",
   license: "MIT",
   type: "module",
@@ -11470,8 +11470,8 @@ function parseHours(v) {
 function readFields(data, keyLine, order) {
   const m = emptyModel();
   const out = [];
-  const L = (k) => keyLine[k] ?? null;
-  const add = (code, k, args = {}) => out.push(finding(code, L(k), args));
+  const L2 = (k) => keyLine[k] ?? null;
+  const add = (code, k, args = {}) => out.push(finding(code, L2(k), args));
   for (const k of order) {
     if (KNOWN.has(k) || k.startsWith("x-"))
       continue;
@@ -13088,6 +13088,129 @@ async function runDoctor(ctx) {
   return 0;
 }
 
+// src/core/i18n.ts
+var T = {
+  "resume.none": { fa: "\u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644\u06CC \u067E\u06CC\u062F\u0627 \u0646\u0634\u062F", en: "no active card found" },
+  "resume.several": { fa: "\u0686\u0646\u062F \u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644 \u0647\u0633\u062A\u061B \u06CC\u06A9\u06CC \u0631\u0627 \u0645\u0634\u062E\u0635 \u06A9\u0646\u06CC\u062F", en: "several active cards; name one" },
+  "resume.never": { fa: "\u0627\u06CC\u0646 \u067E\u0631\u0648\u0698\u0647 \u0647\u0646\u0648\u0632 \u0647\u06CC\u0686\u200C\u0648\u0642\u062A sync \u0646\u0634\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "this project has never been synced; run rodo sync" },
+  "resume.stale": { fa: "\u0622\u062E\u0631\u06CC\u0646 sync \u0628\u06CC\u0634 \u0627\u0632 \u06CC\u06A9 \u0633\u0627\u0639\u062A \u067E\u06CC\u0634 \u0628\u0648\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "last sync is older than 1 hour; run rodo sync" },
+  "status.waitingDecision": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0635\u0645\u06CC\u0645 \u0634\u0645\u0627", en: "waiting for your decision" },
+  "status.waitingApproval": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0623\u06CC\u06CC\u062F \u0634\u0645\u0627", en: "waiting for approval" },
+  "test.none": { fa: "\u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u062F\u0633\u062A\u0648\u0631 \u062A\u0633\u062A \u062A\u0639\u0631\u06CC\u0641 \u0646\u0634\u062F\u0647 (\u062A\u0633\u062A \u0627\u062E\u062A\u06CC\u0627\u0631\u06CC \u0627\u0633\u062A)", en: "no test command for this card (tests are optional)" },
+  "offline.note": { fa: "\u062D\u0627\u0644\u062A \u0622\u0641\u0644\u0627\u06CC\u0646: \u0641\u0642\u0637 \u0628\u0631\u0631\u0633\u06CC \u06A9\u0627\u0631\u062A\u200C\u0647\u0627 \u0627\u0646\u062C\u0627\u0645 \u0634\u062F", en: "offline: cards were validated only" }
+};
+function pickLang(flag, projectLang) {
+  return flag === "fa" || flag === "en" ? flag : projectLang === "en" ? "en" : "fa";
+}
+var t = (lang, key2) => T[key2]?.[lang] ?? key2;
+
+// src/commands/shared.ts
+var LEGACY_MSG = "LEGACY_LAYOUT: run rodo init to move rodo/ into rodo/<project>/";
+function load(ctx, defaultToCwd) {
+  const d = discover(ctx.cwd);
+  const refs = selectProjects(d, ctx.opts.project ?? [], defaultToCwd);
+  const broken = refs.find((r) => r.problem);
+  if (broken) throw new CliError("PROJECT_INVALID", `rodo/${broken.slug}: ${broken.problem}`, 3);
+  if (!refs.length) throw notRepo("no RODO project found: run rodo init --method-only");
+  return { d, refs };
+}
+var fmt = (c, f, icon) => `  ${icon} ${c.path}${f.line ? `:${f.line}` : ""}  ${f.message}`;
+function printFindings(ctx, cards) {
+  for (const c of cards) {
+    for (const f of c.errors) ctx.out.line(fmt(c, f, mark.err));
+    for (const f of c.warnings) ctx.out.line(fmt(c, f, mark.warn));
+  }
+}
+var sum = (cards) => ({
+  files: cards.length,
+  errors: cards.reduce((n, c) => n + c.errors.length, 0),
+  warnings: cards.reduce((n, c) => n + c.warnings.length, 0)
+});
+var slim = (f) => ({ code: f.code, line: f.line, message: f.message });
+
+// src/commands/select.ts
+function oneProject(ctx) {
+  const { d, refs } = load(ctx, true);
+  if (refs.length !== 1) throw usage(`several projects (${refs.map((r) => r.slug).join(", ")}): use --project <slug>`);
+  return { d, ref: refs[0] };
+}
+function pickCard(cards, query) {
+  if (query) {
+    const c = findCard(cards, query);
+    if (!c) throw usage(`no card matches "${query}"`);
+    return c;
+  }
+  for (const status of ["in_progress", "blocked"]) {
+    const list = cards.filter((c) => c.model?.status === status);
+    if (list.length === 1) return list[0];
+    if (list.length > 1) throw usage(`several ${status} cards, name one:
+${list.map((c) => `  ${c.number ?? c.key}  ${c.model?.title}`).join("\n")}`);
+  }
+  throw new CliError("NO_ACTIVE_CARD", "no in_progress or blocked card; name one (rodo resume <card>)", 2);
+}
+function projectCards(ctx) {
+  const { d, ref } = oneProject(ctx);
+  return { d, ref, cards: scanCards(d.root, ref) };
+}
+
+// src/commands/explain.ts
+var L = {
+  status_todo: { fa: "\u0628\u0631\u0646\u0627\u0645\u0647\u200C\u0631\u06CC\u0632\u06CC \u0634\u062F\u0647\u060C \u0647\u0646\u0648\u0632 \u0634\u0631\u0648\u0639 \u0646\u0634\u062F\u0647", en: "planned, not started yet" },
+  status_in_progress: { fa: "\u062F\u0631 \u062D\u0627\u0644 \u0627\u0646\u062C\u0627\u0645", en: "in progress" },
+  status_blocked: { fa: "\u0645\u062A\u0648\u0642\u0641 \u0634\u062F\u0647", en: "stopped" },
+  status_cancelled: { fa: "\u0644\u063A\u0648 \u0634\u062F\u0647", en: "cancelled" },
+  status_done: { fa: "\u062A\u0645\u0627\u0645 \u0634\u062F\u0647", en: "finished" },
+  what: { fa: "\u0686\u0647 \u0686\u06CC\u0632\u06CC \u0645\u06CC\u200C\u06AF\u06CC\u0631\u06CC\u062F", en: "What you get" },
+  state: { fa: "\u0648\u0636\u0639\u06CC\u062A", en: "State" },
+  steps: { fa: "\u0642\u062F\u0645\u200C\u0647\u0627", en: "Steps" },
+  left: { fa: "\u0628\u0627\u0642\u06CC\u200C\u0645\u0627\u0646\u062F\u0647", en: "Still to do" },
+  why: { fa: "\u062F\u0644\u06CC\u0644 \u062A\u0648\u0642\u0641", en: "Why it stopped" },
+  noText: { fa: "\u0647\u0646\u0648\u0632 \u062A\u0648\u0636\u06CC\u062D \u0633\u0627\u062F\u0647\u200C\u0627\u06CC \u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u0646\u0648\u0634\u062A\u0647 \u0646\u0634\u062F\u0647", en: "no plain description has been written for this card yet" }
+};
+function intro(body) {
+  const out = [];
+  for (const raw of body.split(/\r?\n/)) {
+    if (raw.startsWith("## ")) break;
+    const l = raw.trim();
+    if (l && !/\{\{.*\}\}/.test(l)) out.push(l);
+  }
+  return out;
+}
+async function runExplain(ctx, query) {
+  const { ref, cards } = projectCards(ctx);
+  const card = pickCard(cards, query);
+  const m = card.model;
+  if (!m) {
+    ctx.out.line(`${card.path} is not a readable card:`);
+    for (const e2 of card.errors) ctx.out.line(`  ${e2.message}`);
+    ctx.out.flush({ version: 1, card: card.key, errors: card.errors });
+    return 2;
+  }
+  const lang = pickLang(ctx.opts.lang, ref.project?.language.simple);
+  const tr = (k) => L[k][lang];
+  const items = m.checklists.flatMap((c) => c.items);
+  const done = items.filter((i) => i.isDone).length;
+  const left = items.filter((i) => !i.isDone).map((i) => i.title).slice(0, 5);
+  const text = intro(m.description);
+  const title = card.number ? cardLabel(card.number, m.title, " \u2014 ") : m.title;
+  ctx.out.line(title);
+  ctx.out.line(`${tr("state")}: ${tr(`status_${m.status}`)}`);
+  if (m.statusReason) ctx.out.line(`${tr("why")}: ${m.statusReason}`);
+  ctx.out.line("");
+  ctx.out.line(`${tr("what")}:`);
+  (text.length ? text : [tr("noText")]).forEach((l) => ctx.out.line(`  ${l}`));
+  if (items.length) {
+    ctx.out.line("");
+    ctx.out.line(`${tr("steps")}: ${done}/${items.length}`);
+    if (left.length) {
+      ctx.out.line(`${tr("left")}:`);
+      left.forEach((l) => ctx.out.line(`  - ${l}`));
+    }
+  }
+  ctx.out.flush({ version: 1, card: card.key, title: m.title, status: m.status, statusReason: m.statusReason ?? null, plain: text, steps: { done, total: items.length }, remaining: left });
+  return 0;
+}
+
 // src/commands/init.ts
 import { existsSync as existsSync14 } from "fs";
 import { basename as basename2, join as join14 } from "path";
@@ -13259,13 +13382,13 @@ function withMarker(raw, marker) {
   const next = bom + (marker ? marker + eol : "") + rest;
   return next === raw ? null : next;
 }
-var slim = (f) => ({ code: f.code, line: f.line, message: f.message });
+var slim2 = (f) => ({ code: f.code, line: f.line, message: f.message });
 function buildReport(slug2, cards, startedAt, over = {}, extra = /* @__PURE__ */ new Map()) {
   const merged = cards.map((c) => {
     const x = extra.get(c.path);
     return { c, errors: [...c.errors, ...x?.errors ?? []], warnings: [...c.warnings, ...x?.warnings ?? []] };
   });
-  const files = merged.filter((m) => m.errors.length || m.warnings.length).map((m) => ({ path: m.c.path, cardId: m.c.model?.id ?? null, errors: m.errors.map(slim), warnings: m.warnings.map(slim) }));
+  const files = merged.filter((m) => m.errors.length || m.warnings.length).map((m) => ({ path: m.c.path, cardId: m.c.model?.id ?? null, errors: m.errors.map(slim2), warnings: m.warnings.map(slim2) }));
   return {
     version: 1,
     project: slug2,
@@ -14069,32 +14192,6 @@ async function chooseLanguage(ctx, env = process.env) {
 // src/commands/new.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync10, readdirSync as readdirSync5, readFileSync as readFileSync12, writeFileSync as writeFileSync3 } from "fs";
 import { join as join15, relative as relative5, sep as sep2 } from "path";
-
-// src/commands/shared.ts
-var LEGACY_MSG = "LEGACY_LAYOUT: run rodo init to move rodo/ into rodo/<project>/";
-function load(ctx, defaultToCwd) {
-  const d = discover(ctx.cwd);
-  const refs = selectProjects(d, ctx.opts.project ?? [], defaultToCwd);
-  const broken = refs.find((r) => r.problem);
-  if (broken) throw new CliError("PROJECT_INVALID", `rodo/${broken.slug}: ${broken.problem}`, 3);
-  if (!refs.length) throw notRepo("no RODO project found: run rodo init --method-only");
-  return { d, refs };
-}
-var fmt = (c, f, icon) => `  ${icon} ${c.path}${f.line ? `:${f.line}` : ""}  ${f.message}`;
-function printFindings(ctx, cards) {
-  for (const c of cards) {
-    for (const f of c.errors) ctx.out.line(fmt(c, f, mark.err));
-    for (const f of c.warnings) ctx.out.line(fmt(c, f, mark.warn));
-  }
-}
-var sum = (cards) => ({
-  files: cards.length,
-  errors: cards.reduce((n, c) => n + c.errors.length, 0),
-  warnings: cards.reduce((n, c) => n + c.warnings.length, 0)
-});
-var slim2 = (f) => ({ code: f.code, line: f.line, message: f.message });
-
-// src/commands/new.ts
 function slugify2(title) {
   return title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").split("-").slice(0, 6).join("-");
 }
@@ -14159,22 +14256,6 @@ async function runNew(ctx, title, o) {
 import { existsSync as existsSync17, readFileSync as readFileSync14 } from "fs";
 import { dirname as dirname8, join as join17 } from "path";
 
-// src/core/i18n.ts
-var T = {
-  "resume.none": { fa: "\u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644\u06CC \u067E\u06CC\u062F\u0627 \u0646\u0634\u062F", en: "no active card found" },
-  "resume.several": { fa: "\u0686\u0646\u062F \u06A9\u0627\u0631\u062A \u0641\u0639\u0627\u0644 \u0647\u0633\u062A\u061B \u06CC\u06A9\u06CC \u0631\u0627 \u0645\u0634\u062E\u0635 \u06A9\u0646\u06CC\u062F", en: "several active cards; name one" },
-  "resume.never": { fa: "\u0627\u06CC\u0646 \u067E\u0631\u0648\u0698\u0647 \u0647\u0646\u0648\u0632 \u0647\u06CC\u0686\u200C\u0648\u0642\u062A sync \u0646\u0634\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "this project has never been synced; run rodo sync" },
-  "resume.stale": { fa: "\u0622\u062E\u0631\u06CC\u0646 sync \u0628\u06CC\u0634 \u0627\u0632 \u06CC\u06A9 \u0633\u0627\u0639\u062A \u067E\u06CC\u0634 \u0628\u0648\u062F\u0647\u061B rodo sync \u0631\u0627 \u0627\u062C\u0631\u0627 \u06A9\u0646\u06CC\u062F", en: "last sync is older than 1 hour; run rodo sync" },
-  "status.waitingDecision": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0635\u0645\u06CC\u0645 \u0634\u0645\u0627", en: "waiting for your decision" },
-  "status.waitingApproval": { fa: "\u0645\u0646\u062A\u0638\u0631 \u062A\u0623\u06CC\u06CC\u062F \u0634\u0645\u0627", en: "waiting for approval" },
-  "test.none": { fa: "\u0628\u0631\u0627\u06CC \u0627\u06CC\u0646 \u06A9\u0627\u0631\u062A \u062F\u0633\u062A\u0648\u0631 \u062A\u0633\u062A \u062A\u0639\u0631\u06CC\u0641 \u0646\u0634\u062F\u0647 (\u062A\u0633\u062A \u0627\u062E\u062A\u06CC\u0627\u0631\u06CC \u0627\u0633\u062A)", en: "no test command for this card (tests are optional)" },
-  "offline.note": { fa: "\u062D\u0627\u0644\u062A \u0622\u0641\u0644\u0627\u06CC\u0646: \u0641\u0642\u0637 \u0628\u0631\u0631\u0633\u06CC \u06A9\u0627\u0631\u062A\u200C\u0647\u0627 \u0627\u0646\u062C\u0627\u0645 \u0634\u062F", en: "offline: cards were validated only" }
-};
-function pickLang(flag, projectLang) {
-  return flag === "fa" || flag === "en" ? flag : projectLang === "en" ? "en" : "fa";
-}
-var t = (lang, key2) => T[key2]?.[lang] ?? key2;
-
 // src/core/time.ts
 var fmtFor = (timeZone) => new Intl.DateTimeFormat("sv-SE", {
   timeZone,
@@ -14431,31 +14512,6 @@ function streak(previous, sig) {
 }
 var STUCK_MESSAGE = (sig) => `RODO_STUCK: the same failure happened twice (${sig}). Per the RODO method: set status: blocked, blockerType: test or technical, write the reason in statusReason, and ask the user.`;
 
-// src/commands/select.ts
-function oneProject(ctx) {
-  const { d, refs } = load(ctx, true);
-  if (refs.length !== 1) throw usage(`several projects (${refs.map((r) => r.slug).join(", ")}): use --project <slug>`);
-  return { d, ref: refs[0] };
-}
-function pickCard(cards, query) {
-  if (query) {
-    const c = findCard(cards, query);
-    if (!c) throw usage(`no card matches "${query}"`);
-    return c;
-  }
-  for (const status of ["in_progress", "blocked"]) {
-    const list = cards.filter((c) => c.model?.status === status);
-    if (list.length === 1) return list[0];
-    if (list.length > 1) throw usage(`several ${status} cards, name one:
-${list.map((c) => `  ${c.number ?? c.key}  ${c.model?.title}`).join("\n")}`);
-  }
-  throw new CliError("NO_ACTIVE_CARD", "no in_progress or blocked card; name one (rodo resume <card>)", 2);
-}
-function projectCards(ctx) {
-  const { d, ref } = oneProject(ctx);
-  return { d, ref, cards: scanCards(d.root, ref) };
-}
-
 // src/commands/resume.ts
 var MAP_WHAT = /^##\s*(این پروژه چیست|What this project is)/i;
 var MAP_WHERE = /^##\s*(الان کجاییم|Where we are)/i;
@@ -14784,7 +14840,7 @@ async function runValidate(ctx, paths, o = {}) {
     if (ref.legacy) ctx.out.line(LEGACY_MSG);
     ctx.out.line(`rodo/${ref.legacy ? "" : ref.slug}  \u25B8 ${s.files} files \xB7 errors ${s.errors} \xB7 warnings ${s.warnings}`);
     printFindings(ctx, cards);
-    for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim2), warnings: c.warnings.map(slim2) });
+    for (const c of cards) files.push({ project: ref.slug, path: c.path, errors: c.errors.map(slim), warnings: c.warnings.map(slim) });
   }
   ctx.out.flush({ version: 2, files, summary: total });
   return o.strict && total.errors > 0 ? 1 : 0;
@@ -14799,6 +14855,7 @@ Getting started:
   rodo new "Delete a note"                   start the next cycle (card, simple.md, spec.md)
   rodo validate --strict                     check the cards (exit 1 on errors)
   rodo resume <card>                         context for an AI session
+  rodo explain <card>                        the card in plain words, for you
   rodo test <card>                           run the card test and catch repeated failures
   rodo init --project <slug> --create-board  later: connect a board, then rodo sync`);
   program2.command("init").description("install or update the method kit and create a project folder").option("--name <name>", "display name").option("--server <url>", "board server (default: RODO_SERVER, else the built-in server)").option("--connect <code>", "one-time connect code from the board website (skips the device code)").option("--board <id>", "bind to an existing board").option("--create-board", "create a new board for this project").option("--method-only", "no server: install the kit and create the project folder only").option("--no-kit-update", "skip the kit step").option("--dry-run", "print the plan, write nothing").option("--yes-files", "answer yes to the .gitignore question").addHelpText("after", `
@@ -14815,6 +14872,7 @@ Examples:
   program2.command("status").description("cards and their state").option("--local").action((o) => run((ctx) => runStatus(ctx, o)));
   program2.command("doctor").description("read-only health checks").action(() => run((ctx) => runDoctor(ctx)));
   program2.command("resume [card]").description("print the context of a card for an AI session").option("--full").action((card, o) => run((ctx) => runResume(ctx, card, o)));
+  program2.command("explain [card]").description("describe a card in plain words for the user (read-only)").action((card) => run((ctx) => runExplain(ctx, card)));
   program2.command("test [card]").description("run the card test command and track failure signatures").option("--adapter <adapter>", "web|api|cli|mobile|iot|other").action((card, o) => run((ctx) => runTest(ctx, card, o)));
   program2.command("version").description("versions").action(() => run((ctx) => runVersion(ctx)));
   return program2;

package/dist/kit/.agents/skills/rodo/SKILL.md

@@ -5,7 +5,7 @@ description: RODO project method. Use whenever the repo has a rodo/ folder or *.
 
 > یادداشت فارسی: این مهارت برای AI است. نسخهٔ انسانی همین قواعد در `rodo/<project>/RULES.md` است. RODO فقط «روش کار» است: هیچ ابزاری جلوی commit، تست یا کار را نمی‌گیرد.
 
-# RODO method (kit 2.2.1)
+# RODO method (kit 2.4.0)
 
 RODO is a way of working, not a gate. Nothing blocks a commit, a test or a status. You follow it because it keeps the project understandable for the user, for teammates and for the next AI session.
 
@@ -86,6 +86,8 @@ A card may have `scope: {allowed: [...], forbidden: [...]}`. Stay inside `allowe
 | The repo has code but no `rodo/<project>/` yet | `onboarding.md` |
 | Typo, style, refactor or a fix that does not change described behaviour | `small-change.md` |
 | You write or fix tests (optional, recommended) | `testing.md` |
+| Before closing any card: keep the code small and clean | `clean.md` |
+| Review before closing a MAJOR card, or on request | `review.md` |
 
 ## Workflow levels
 
@@ -159,6 +161,7 @@ Card format details: the comments in `templates/card.rodo.md` and `rodo validate
 | `rodo sync` | start and end of every session |
 | `rodo resume [card] [--full]` | context for a new session |
 | `rodo status` | board vs local, side by side |
+| `rodo explain [card]` | the card in plain words, for the user |
 | `rodo test [card]` | run the card's test command, record the failure signature |
 | `rodo new "<title>"` | create the next cycle folder with `card.rodo.md`, `simple.md`, `spec.md` (`--major` adds `design.md` and `acceptance.feature`) |
 | `rodo validate` | check card files (never blocks; `--strict` exits 1 on errors, for CI) |

package/dist/kit/.agents/skills/rodo/clean.md

@@ -0,0 +1,33 @@
+# Clean code formulas
+
+Short rules for code you write or touch in a card. They keep the project small and easy to extend. Apply them to the files of this card only; never start a repo-wide cleanup without a card of its own.
+
+## The formulas
+
+| Rule | Limit |
+|---|---|
+| One function does one thing | about 30 lines |
+| One file has one reason to change | about 300 lines; split by responsibility, not by size alone |
+| Parameters | 3 or fewer; more → pass one object |
+| Nesting | 3 levels or fewer; use early `return` |
+| Repetition | the third copy becomes a shared function; two copies stay (do not guess early) |
+| Names | say what, not how (`overdueInvoices`, not `list2`); no abbreviations the glossary does not know |
+| Comments | only the *why*; delete comments that repeat the code |
+| Dead code | delete it (git remembers); never comment code out |
+| New dependency | only if it replaces more than ~50 lines you would write and keep; mention it in `spec.md` `## Decisions` |
+| Extension | add a new file or a new entry in a list, not a new `if` inside a long function |
+
+## Order of work (every card)
+
+1. Make it work (R-rules pass).
+2. Read your own diff once. Apply the formulas above to what you changed.
+3. Remove what is now unused: imports, variables, files, docs that describe the removed behaviour.
+4. Match the surrounding style (naming, comment density, error handling). Do not reformat code you did not change.
+5. Re-run the checks. Cleaning must not change behaviour.
+6. Tick the card's `Cleanup done` step and write `- Cleaned: <what you simplified, or "nothing needed">` in Progress notes.
+
+## Boundaries
+
+- A cleanup that touches files outside the card's `scope.allowed` is a new card (SKILL.md "Scope").
+- If a formula forces a large rewrite, do not do it silently: write `- Out of scope: <refactor> → new card` and tell the user.
+- Prefer deleting over adding. The best change is the one with fewer lines for the same behaviour.

package/dist/kit/.agents/skills/rodo/coder.md

@@ -1,82 +1,86 @@
-> یادداشت فارسی: دستورالعمل کدنویس. از روی کارت کار کن، فقط ارجاع‌ها را بخوان، قدم‌به‌قدم جلو برو، سندها را درست نگه دار، و آخر هر جلسه «Progress notes» را به‌روز کن. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
-
-# Coder playbook
-
-You implement one card. Any model may do this; the user chooses.
-
-## Before you start (every session)
-
-Follow "Session start" in SKILL.md (git check without pulling → rodo sync → rodo resume → refs only → approval check → answered decisions). Then set `status: in_progress`.
-
-## Doing the steps
-
-For each unticked step, in order:
-1. Do only what the step says.
-2. Check it (unit test, build, or the command the step names).
-3. Tick it `- [x]`; add `[hours: H:MM]` only if you know the real time.
-4. Commit with the card number in the message, e.g. `feat: discount code input [cycle 002]`, so people can find the work later.
-
-If your change makes a project doc wrong (`project/*`, the card's `spec.md`), fix the doc in the same commit.
-
-## Tests (if the card has scenarios)
-
-- Step definitions go in the folder from `project.json` `stepsDirs`. They must really drive the app (browser, API or CLI) and really assert. See `testing.md`.
-- Run the card's tests with `rodo test` (it uses the card's `test.command`, or `testCommand` from `project.json`). Tick `تست پذیرش پاس شد` only after a real passing run.
-- **Never weaken a scenario or test to make code pass:** no deleting scenarios, loosening assertions, `@skip`/`.only`/`test.fixme`, or changing an expected value to match buggy output. If a scenario looks wrong, explain why to the user; change it only if they agree.
-
-## Scope changes while coding
-
-- Out of the card's `scope` or a new requirement: do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes and tell the user.
-- Small change in the same feature: update the scenario/spec/steps of this card, tell the user, continue (wait if there is an unticked approval item).
-- Big new feature: do not add it. Write it under `- Remaining:` as "needs a new card" and tell the user.
-
-## Stuck
-
-Use the stuck rule in SKILL.md: same failure signature twice → `status: blocked`, `blockerType: test` or `technical`, a plain `statusReason:`, ask the user. Waiting for an answer, a key or another card → `status: blocked` with the matching `blockerType` (`decision`, `permission`, `external`). If only the user can choose, write a `## Decision:` section (SKILL.md). When solved: `status: in_progress`, remove `statusReason` and `blockerType`. Never set `cancelled` yourself; only with the user's OK.
-
-## Verify and fix
-
-**VERIFY** — pick the checks that fit this change and run them with the project's own tools (RODO runs nothing itself):
-- build, typecheck, lint;
-- unit, integration, e2e;
-- architecture rules, security checks;
-- acceptance (the card's `test` command via `rodo test`, or the acceptance criteria checked one by one);
-- documentation consistency (below).
-
-Write the result in Progress notes as `- Verified: <check> ✓/✗, …`.
-
-**Documentation Consistency** (part of VERIFY):
-- Check that every file listed under Documentation Impact was updated.
-- Check that the CURRENT docs and the active cycle docs still describe the code.
-- If something does not match: FIX, then VERIFY again.
-- If a current doc contradicts a `MEMORY.md` decision, stop and ask the user (as small-change.md already says).
-
-**REVIEW (optional; recommended for MAJOR)** — an independent AI session or model reads the change and checks:
-- requirement coverage; acceptance criteria;
-- regressions; architecture fit;
-- missing tests; maintainability;
-- unintended changes.
-
-A review never replaces tests. Its findings go back to FIX.
-
-**FIX loop** — FIX → VERIFY until everything passes (→ DONE) or the stuck rule applies: the **same failure twice** (same failure signature, or the same error at the same place) → `status: blocked` with `blockerType: test` or `technical` (SKILL.md "Stuck rule"). Different failures do not count.
-
-## End of every session
-
-Follow "Session close" in SKILL.md. Always finish with `rodo sync`.
-
-## Close (all steps ticked)
-
-The folder does not move.
-1. Card: `status: done`.
-2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
-3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
-4. Commit the MAP and MEMORY change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
-
-## Rules
-
-- Never tick an approval item or change its text. Only a person can approve, in the web app. Never answer a `## Decision:` yourself.
-- Never edit `id:` lines or `<!-- rodo:... -->` comments.
-- Do not change `members`, `startAt`, `dueAt`, `priority` unless the user asks: the team owns them.
-- Never delete files you did not create in this card without asking.
-- Keep changes inside the steps. Unrelated fixes go to `small-change.md` or a new card.
+> یادداشت فارسی: دستورالعمل کدنویس. از روی کارت کار کن، فقط ارجاع‌ها را بخوان، قدم‌به‌قدم جلو برو، سندها را درست نگه دار، و آخر هر جلسه «Progress notes» را به‌روز کن. همهٔ مسیرها نسبت به `rodo/<project>/` هستند.
+
+# Coder playbook
+
+You implement one card. Any model may do this; the user chooses.
+
+## Before you start (every session)
+
+Follow "Session start" in SKILL.md (git check without pulling → rodo sync → rodo resume → refs only → approval check → answered decisions). Then set `status: in_progress`.
+
+## Doing the steps
+
+For each unticked step, in order:
+1. Do only what the step says.
+2. Check it (unit test, build, or the command the step names).
+3. Tick it `- [x]`; add `[hours: H:MM]` only if you know the real time.
+4. Commit with the card number in the message, e.g. `feat: discount code input [cycle 002]`, so people can find the work later.
+
+If your change makes a project doc wrong (`project/*`, the card's `spec.md`), fix the doc in the same commit.
+
+## Tests (if the card has scenarios)
+
+- Step definitions go in the folder from `project.json` `stepsDirs`. They must really drive the app (browser, API or CLI) and really assert. See `testing.md`.
+- Run the card's tests with `rodo test` (it uses the card's `test.command`, or `testCommand` from `project.json`). Tick `تست پذیرش پاس شد` only after a real passing run.
+- **Never weaken a scenario or test to make code pass:** no deleting scenarios, loosening assertions, `@skip`/`.only`/`test.fixme`, or changing an expected value to match buggy output. If a scenario looks wrong, explain why to the user; change it only if they agree.
+
+## Scope changes while coding
+
+- Out of the card's `scope` or a new requirement: do not do it silently. Write `- Out of scope: <item> → new card` in Progress notes and tell the user.
+- Small change in the same feature: update the scenario/spec/steps of this card, tell the user, continue (wait if there is an unticked approval item).
+- Big new feature: do not add it. Write it under `- Remaining:` as "needs a new card" and tell the user.
+
+## Stuck
+
+Use the stuck rule in SKILL.md: same failure signature twice → `status: blocked`, `blockerType: test` or `technical`, a plain `statusReason:`, ask the user. Waiting for an answer, a key or another card → `status: blocked` with the matching `blockerType` (`decision`, `permission`, `external`). If only the user can choose, write a `## Decision:` section (SKILL.md). When solved: `status: in_progress`, remove `statusReason` and `blockerType`. Never set `cancelled` yourself; only with the user's OK.
+
+## Verify and fix
+
+**VERIFY** — pick the checks that fit this change and run them with the project's own tools (RODO runs nothing itself):
+- build, typecheck, lint;
+- unit, integration, e2e;
+- architecture rules, security checks;
+- acceptance (the card's `test` command via `rodo test`, or the acceptance criteria checked one by one);
+- documentation consistency (below).
+
+Write the result in Progress notes as `- Verified: <check> ✓/✗, …`.
+
+**Documentation Consistency** (part of VERIFY):
+- Check that every file listed under Documentation Impact was updated.
+- Check that the CURRENT docs and the active cycle docs still describe the code.
+- If something does not match: FIX, then VERIFY again.
+- If a current doc contradicts a `MEMORY.md` decision, stop and ask the user (as small-change.md already says).
+
+**REVIEW (optional; recommended for MAJOR)** — an independent AI session or model reads the change and checks:
+- requirement coverage; acceptance criteria;
+- regressions; architecture fit;
+- missing tests; maintainability;
+- unintended changes.
+
+A review never replaces tests. Its findings go back to FIX.
+
+**FIX loop** — FIX → VERIFY until everything passes (→ DONE) or the stuck rule applies: the **same failure twice** (same failure signature, or the same error at the same place) → `status: blocked` with `blockerType: test` or `technical` (SKILL.md "Stuck rule"). Different failures do not count.
+
+## Clean before you close
+
+When the steps are done and verified, follow `clean.md` (and `review.md` for MAJOR), then tick `Cleanup done`.
+
+## End of every session
+
+Follow "Session close" in SKILL.md. Always finish with `rodo sync`.
+
+## Close (all steps ticked)
+
+The folder does not move.
+1. Card: `status: done`.
+2. `MAP.md`: add the cycle under `## انجام‌شده` (one line, link to simple.md or the card folder) and update "الان کجاییم".
+3. `MEMORY.md`: append each `## Decisions` line of spec.md as `- YYYY-MM-DD — <decision>. چون <reason>. (cycle NNN)`.
+4. Commit the MAP and MEMORY change. Later changes to this behaviour need a new card; changes that do not touch behaviour go to `small-change.md`.
+
+## Rules
+
+- Never tick an approval item or change its text. Only a person can approve, in the web app. Never answer a `## Decision:` yourself.
+- Never edit `id:` lines or `<!-- rodo:... -->` comments.
+- Do not change `members`, `startAt`, `dueAt`, `priority` unless the user asks: the team owns them.
+- Never delete files you did not create in this card without asking.
+- Keep changes inside the steps. Unrelated fixes go to `small-change.md` or a new card.

package/dist/kit/.agents/skills/rodo/review.md

@@ -0,0 +1,30 @@
+# Review checklists
+
+Use before closing a MAJOR card (recommended) or whenever the user asks for a review. A review reads the diff; it never replaces tests. Report findings in plain words, most serious first, and fix them (FIX → VERIFY).
+
+## 1. Simplify (always)
+
+- Anything duplicated, over-built, or unused in the diff?
+- Could a simpler existing function or library call replace new code?
+- Follow `clean.md`.
+
+## 2. Correctness
+
+- Does each R-rule of `spec.md` have code and, if tests are used, a test?
+- Edge cases: empty input, missing value, very large input, two things happening at once.
+- Errors: are they handled or reported, never swallowed?
+
+## 3. Security (quick pass)
+
+- No secrets in code, config, logs, cards or commit messages.
+- Input from outside (forms, URLs, files, env) is checked before use; no string-built SQL, shell commands or HTML.
+- Access: every new route or action checks who is calling.
+- New dependencies: known, maintained, and necessary.
+
+## 4. Plain words
+
+- Does the card's opening text (what the user gets) and `simple.md` still describe what the code now does? Run `rodo explain <card>` and read it as if you were not a developer.
+
+## Optional external skills
+
+If the project or the user's tools already provide them, you may use `simplify`, `code-review`, `security-review` or Graphify (code map). Never install them yourself; RODO works without them. Treat their output as advice and verify it before acting.

package/dist/kit/.agents/skills/rodo/templates/card.rodo.md

@@ -11,7 +11,7 @@ scope:
   forbidden: []
 ---
 
-{{دو تا پنج خط ساده: کاربر چه چیزی می‌گیرد. جزئیات در spec.md است.}}
+{{دو تا پنج خط ساده و بدون اصطلاح فنی: کاربر چه چیزی می‌گیرد. دستور rodo explain همین را به کاربر نشان می‌دهد. جزئیات در spec.md است.}}
 
 ## Progress notes
 
@@ -30,4 +30,5 @@ scope:
 <!-- - [ ] تأیید کاربر: simple.md و سناریوها [approval] — add only when the user asked for a human approval (D5) -->
 - [ ] {{قدم ۱: کار مشخص + نشانهٔ انجام شدن}}
 - [ ] {{قدم ۲}}
+- [ ] تمیزکاری انجام شد (clean.md)
 - [ ] تست پذیرش پاس شد

package/dist/kit/.agents/skills/rodo/templates/en/card.rodo.md

@@ -1,32 +1,33 @@
----
-schemaVersion: 2
-title: "{{short title}}"
-status: todo
-# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
-priority: medium
-# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
-members: []
-scope:
-  allowed: []
-  forbidden: []
----
-
-{{two to five plain lines: what the user gets. Details are in spec.md.}}
-
-## Progress notes
-
-- Updated: {{YYYY-MM-DD}}
-- Done: not started yet
-- Remaining: all steps
-
-## Refs
-
-- [Plain explanation](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
-- [Technical spec](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
-<!-- [Acceptance scenarios](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
-
-## Checklist: Steps
-
-<!-- - [ ] User approval: simple.md and scenarios [approval] — add only when the user asked for a human approval -->
-- [ ] {{step 1: a concrete task + how you know it is done}}
-- [ ] {{step 2}}
+---
+schemaVersion: 2
+title: "{{short title}}"
+status: todo
+# statusReason: ...   # only when status is blocked or cancelled: the reason in plain words
+priority: medium
+# workflow: standard   # optional: quick | standard | major; local only, never sent to the board
+members: []
+scope:
+  allowed: []
+  forbidden: []
+---
+
+{{two to five plain lines: what the user gets, with no technical terms. `rodo explain` shows exactly this to the user. Details are in spec.md.}}
+
+## Progress notes
+
+- Updated: {{YYYY-MM-DD}}
+- Done: not started yet
+- Remaining: all steps
+
+## Refs
+
+- [Plain explanation](/rodo/{{project}}/cycles/{{NNN-slug}}/simple.md)
+- [Technical spec](/rodo/{{project}}/cycles/{{NNN-slug}}/spec.md)
+<!-- [Acceptance scenarios](/rodo/{{project}}/cycles/{{NNN-slug}}/acceptance.feature) — uncomment only after that file exists -->
+
+## Checklist: Steps
+
+<!-- - [ ] User approval: simple.md and scenarios [approval] — add only when the user asked for a human approval -->
+- [ ] {{step 1: a concrete task + how you know it is done}}
+- [ ] {{step 2}}
+- [ ] Cleanup done (clean.md)

package/dist/kit/KIT_VERSION

@@ -1 +1 @@
-2.2.1
+2.4.0