@sylad/cadence 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "cadence",
+  "description": "cadence — a repo-native working method for Claude Code sessions",
+  "owner": { "name": "Sylvain Ladoire" },
+  "plugins": [
+    {
+      "name": "cadence",
+      "description": "Session start and close rituals driven by a versioned plan (raf), and deliveries proven by their effect. Needs the cadence CLI (npm i -g @sylad/cadence).",
+      "version": "0.2.0",
+      "source": "./",
+      "author": { "name": "Sylvain Ladoire" }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "cadence",
+  "description": "A repo-native working method: session start and close rituals driven by a versioned plan (raf), deliveries proven by their effect, and a UX reviewer agent.",
+  "version": "0.2.0",
+  "author": { "name": "Sylvain Ladoire" },
+  "homepage": "https://github.com/Sylad/cadence",
+  "repository": "https://github.com/Sylad/cadence",
+  "license": "MIT",
+  "keywords": ["planning", "workflow", "delivery", "changelog", "sessions"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sylvain Ladoire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,234 @@
+# cadence
+
+A small working method that lives in your repository. Solo developers and
+AI-assisted sessions lose track of *what is left to do* and *what each commit
+was for*; cadence keeps both in plain files next to the code.
+
+Four tools:
+
+- **raf** (French *reste à faire*, "what is left to do"): the plan, linked to your commits;
+- **news**: a user-facing changelog with screenshots, tied to the plan;
+- **session**: the facts to start and to close a work session;
+- **deliver**: wait for the CI of the pushed commit, deploy, then **verify the effect**.
+
+And three [Claude Code](https://claude.com/claude-code) skills that turn them
+into rituals — `session-start`, `session-close`, `deliver` — plus a `ux-reviewer`
+agent: no user-facing change is done before its usability review.
+
+## raf
+
+- The plan is a YAML file in the repo (`docs/plan/raf.yaml`), edited by the CLI.
+  Your comments and hand edits are preserved.
+- A commit belongs to a lot when its message cites the id: `feat(L3): …`,
+  `fix: L3/t1 …`. The link is **computed from `git log`**, never stored, so
+  committing never dirties the plan.
+- `raf check` audits drift between the plan and the history.
+- `raf gantt` writes a single self-contained HTML page (no server, no CDN).
+
+```sh
+npm install -g @sylad/cadence    # or: npx -p @sylad/cadence raf …
+
+raf init                          # docs/plan/raf.yaml + post-commit hook
+raf add "Monthly dedup on merge" --estimate 2
+raf add "Typo in footer" --quickwin
+raf add "Loan cache" --after L1
+raf add "write the migration" --parent L1     # → L1/t1
+raf start L1
+git commit -m "feat(L1): dedup by calendar month"
+raf now                           # in progress, next up (quickwins first), recently done
+raf done L1/t1 && raf done L1
+raf check                         # exit 1 on drift
+raf gantt                         # docs/plan/gantt.html
+```
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `raf init [--project name] [--prefix L] [--no-hook]` | create the plan and install the hook |
+| `raf add "title" [--estimate d] [--quickwin] [--visible] [--after L2,L4] [--parent L3]` | add a lot or a sub-task, print its id |
+| `raf start <id>` · `raf done <id> [--force]` · `raf drop <id> [--reason text]` | dated transitions (`done` refuses open sub-tasks unless `--force`) |
+| `raf note <id> "text"` | dated note — keep decisions next to the work |
+| `raf now` | what to do next |
+| `raf list [--status s]` | flat list |
+| `raf check [--since date] [--idle 7]` | since the plan's adoption date by default: commits without a lot (commits touching only the plan are exempt), unknown ids, `todo` lots that already have commits, idle lots, `done` lots with open sub-tasks, bad or circular dependencies |
+| `raf gantt [-o file]` | standalone Gantt page |
+| `raf hook install` | add the (non-blocking, read-only) post-commit hook |
+
+Global options: `--file path` or `RAF_FILE`; `RAF_TODAY=YYYY-MM-DD` to freeze
+the date. `cadence raf …` is the same as `raf …`.
+
+### Plan file
+
+```yaml
+version: 1
+project: my-app
+prefix: L
+since: 2026-09-28     # commits before this date are not audited
+lots:
+  - id: L1
+    title: Monthly dedup on merge
+    status: doing        # todo | doing | done | dropped
+    estimate: 2          # working days
+    quickwin: false
+    visible: true        # user-facing: a news entry is expected when done
+    after: [L0]
+    created: 2026-09-28
+    started: 2026-09-29
+    notes:
+      - { date: 2026-09-29, text: "keep the bank line when both sources exist" }
+    tasks:
+      - { id: t1, title: write the migration, status: done }
+```
+
+### Gantt scheduling
+
+One lane of work. Finished lots use their real dates (or their commits' dates);
+lots in progress run until `max(start + estimate, today)`; lots to do follow in
+file order, after their dependencies, on working days.
+
+## news
+
+What changed *for the user*, one entry per visible lot, each with a screenshot.
+
+- Mark a lot as user-facing with `raf add … --visible` (or `visible: true` in
+  the YAML). `raf done` and the post-commit hook remind you to write its entry;
+  `raf check` fails while a visible lot is done without one.
+- An entry is a Markdown file in `docs/nouveautes/`, with a YAML header.
+  Screenshots are files you take yourself, stored next to the entries.
+- `cadence news build` writes `nouveautes.json` for your app to display, a
+  self-contained `index.html`, and copies the screenshots.
+
+```sh
+raf add "Amounts like 3.000 read as three thousand" --visible   # → L8
+raf start L8 && git commit -m "fix(L8): thousands separator" && raf done L8
+cadence news new L8          # docs/nouveautes/2026-09-29-amounts-like-3-000-….md
+# add docs/nouveautes/captures/l8.png, list it under `captures:`, write the text
+cadence news check           # exit 1 on drift (also part of raf check)
+cadence news build -o frontend/public/nouveautes
+```
+
+```markdown
+---
+title: Amounts like 3.000 read as three thousand
+date: 2026-09-29
+lots: [L8]
+captures: [captures/l8.png]
+# nocapture: reason, when a screenshot makes no sense
+---
+Imported statements now read **3.000** as three thousand, not three.
+```
+
+| Command | Effect |
+|---|---|
+| `cadence news new <lot…> [--title t]` | entry skeleton, dated today, titled after the lot |
+| `cadence news list` | entries, newest first |
+| `cadence news check` | visible lots done without entry, unknown lots, missing or undeclared screenshots, bad headers |
+| `cadence news build [-o dir]` | `nouveautes.json` + `index.html` + screenshots (default `docs/nouveautes/site`) |
+
+`--dir` changes the entries folder (default `docs/nouveautes` at the git root).
+The Markdown is deliberately small: paragraphs, `-` lists, `**bold**`,
+`` `code` ``, `[links](url)`; everything else is escaped text. The JSON holds
+`{ project, generated, entries: [{ slug, title, date, lots, captures, html }] }`,
+with screenshot paths relative to the JSON file.
+
+### UX review
+
+```sh
+raf ux enable                      # from today, a --visible lot needs a UX review before done
+raf ux L4 "compliant after 2 fixes"   # record the verdict (from the ux-reviewer agent)
+raf ux L8 "no screen: calculation fix"
+```
+
+With the rule on, `raf done` refuses a visible lot without a review (`--force`
+to override) and `raf check` reports visible lots finished after the `uxSince`
+day without one. Plans without `uxSince` are not affected.
+
+## session
+
+```sh
+cadence session start              # notes from the last close, lots in progress (silent ones flagged),
+                                   # work done since yesterday by lot, drift, repo state, 3 proposals
+cadence session start --since "3 days ago" --idle 2
+cadence session close              # today's commits by lot, commits without a lot, lots in progress
+                                   # with no commit today, drift, uncommitted / unpushed work
+                                   # exit 1 while something is still open
+cadence session next "finish L3" "review L4"    # shown by the next session start
+```
+
+Proposals come from the plan only: lots in progress, then ready lots (dependencies
+done), quick wins first. Local state lives in the git directory, never committed:
+the close notes per worktree, the delivery lock and log in `.git/cadence/`, shared
+by all the worktrees of a clone.
+
+## deliver
+
+A delivery is done when its checks pass, not when a tool says "success".
+
+```yaml
+# cadence.yaml, at the repository root
+deliver:
+  ci: github              # github | none | { command: "…" }   (default: none)
+  ciTimeout: 1800         # seconds
+  deploy:                 # sh commands, in order, at the repo root
+    - ./scripts/deploy.sh "$CADENCE_SHORT"
+  verify:                 # at least one; retried every 10 s until verifyTimeout
+    - url: https://app.example.com/api/health
+      status: 200         # default 200
+    - url: https://app.example.com/version.txt
+      contains: "${SHORT}"
+    - command: kubectl rollout status deploy/app --timeout=60s
+  verifyTimeout: 300
+  deployTimeout: 1800     # seconds, per deploy command
+```
+
+```sh
+cadence deliver --dry-run    # preconditions, then the resolved steps; nothing runs
+cadence deliver              # 0 delivered and verified · 1 a step failed · 2 refused before acting
+```
+
+- **Preconditions**: no modified tracked file; `HEAD` is on a remote branch (the
+  CI can only build what was pushed); no other delivery running (a lock whose
+  process died is removed with a warning); with `ci: github`, `gh` installed and
+  logged in.
+- Every command is killed when it exceeds its budget (CI, `deployTimeout`, what is
+  left of `verifyTimeout`) and reported as "délai dépassé".
+- **CI** `github`: polls `gh run list --commit <sha>` every 15 s; no run after
+  5 minutes is a failure (you probably pushed another commit than the one you
+  deliver); every run must end `success`, `skipped` or `neutral`. `gh` errors
+  are retried, and reported with their cause after 5 minutes.
+- Commands get `CADENCE_SHA`, `CADENCE_SHORT` (7 characters) and `CADENCE_BRANCH`;
+  `${SHA}` and `${SHORT}` are replaced in `url` and `contains`.
+- On success the lots cited by the commits since the previous delivery are
+  listed, so you can `raf done` those whose effect you have seen.
+
+## Claude Code skills
+
+As a plugin:
+
+```
+/plugin marketplace add Sylad/cadence
+/plugin install cadence@cadence
+```
+
+gives `/cadence:session-start`, `/cadence:session-close`, `/cadence:deliver` and
+the `ux-reviewer` agent. Or copy them into the repository with
+`cadence skills install` (to `.claude/skills/cadence-*` and
+`.claude/agents/cadence-ux-reviewer.md`; `--dir` for another `.claude` folder,
+`--force` to overwrite local edits).
+
+- **session-start**: reports the facts briefly, proposes three lots from the
+  plan, then waits for your priority — nothing starts before your answer.
+- **session-close**: plan hygiene, clean repository, memory limited to what the
+  repository does not say, new skills or agents proposed but never created, three
+  lines for next time.
+- **deliver**: dry run, delivery, and on failure the cause fixed rather than a
+  blind retry.
+- **ux-reviewer** (agent): captures at 1440 and 390 px, findings grounded in a
+  named rule (Nielsen, WCAG 2.2 AA) or a measurement, ranked, turned into
+  `raf add --parent` sub-tasks, and a one-line verdict for `raf ux`. It never
+  edits code.
+
+## License
+
+MIT

package/agents/ux-reviewer.md

@@ -0,0 +1,49 @@
+---
+name: ux-reviewer
+description: Usability and accessibility reviewer for any web interface — reviews a page, a screen or a user-facing change before it is marked done, and runs the planned reviews of existing screens. Grounds every finding in a named rule (Nielsen heuristics, WCAG 2.2 AA) or a measurement, never in taste; respects the product's existing visual identity; describes a mockup before any redesign. Use when a lot marked `visible` is about to be closed (`raf ux <lot>`), when a new page is added, or for a "UX review — <screen>" lot. Does not modify code.
+---
+
+You review the usability and accessibility of a web interface. You report; you never edit code.
+
+## Inputs
+
+The lot or screen to review, and how to reach it (local dev server, deployed URL, route). If the
+screen needs data or a login, ask for — or find in the project docs — the way to get a realistic state
+(demo data, stubbed API). Read the project's CLAUDE.md and design notes first: the product's existing
+identity (colours, density, tone) is a constraint, not something to "fix".
+
+## Method
+
+1. **Look before judging.** Capture the screen with the browser tool available (Playwright or
+   equivalent) at **1440 px** and **390 px** wide, in its main states: empty, loaded, error, loading,
+   and the key interaction. Look at every capture. Store them in the project's temporary folder.
+2. **Walk the main task** a real user comes for (find, read, compare, act, undo) and count the steps.
+3. **Check, and measure where a number exists:**
+   - Nielsen's 10 heuristics — especially visibility of system status, match with the user's words,
+     consistency, error prevention and recovery, recognition rather than recall;
+   - WCAG 2.2 AA — text contrast ≥ 4.5:1 (≥ 3:1 for large text and UI parts), everything usable with
+     the keyboard, visible focus, targets ≥ 24×24 px (44 px recommended on touch), text alternatives,
+     no information carried by colour alone, content that reflows at 320 px without horizontal scroll;
+   - data display — units shown, numbers aligned and formatted for the locale, charts readable without
+     their legend colours alone, empty states that say what to do;
+   - on the phone width, a dense control-heavy page is often better **hidden or reduced** than squeezed.
+4. **Rank** each finding: *blocking* (a user cannot complete the task, or an accessibility failure),
+   *major* (slows or misleads), *minor* (polish).
+
+## Output
+
+A short report:
+
+- **Verdict** in one line, suitable for `raf ux <lot> "…"` — e.g. "compliant", "compliant after 2 fixes",
+  "not compliant: 1 blocking".
+- **Findings**, most severe first, each with: what (with the capture), the rule or the measure, the
+  proposed change, the effort (S ≤ a session, M ≈ a day).
+- **Proposed sub-tasks**: one `raf add --parent <lot> "…"` line per finding worth doing.
+- For any redesign, a **described mockup** (layout, hierarchy, what moves where) to be approved before
+  anyone codes it.
+
+## Do not
+
+- Judge on taste, or propose a new visual identity.
+- Report a finding you have not seen in a capture or measured.
+- Edit code, commit, or record `raf ux` yourself: the session that owns the lot does it.

package/bin/cadence.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { run } from '../dist/cli.js';
+
+const [tool, ...args] = process.argv.slice(2);
+const io = {
+  cwd: process.cwd(),
+  env: process.env,
+  out: (l) => console.log(l),
+  err: (l) => console.error(l),
+  now: () => new Date(),
+};
+
+if (tool === 'raf') {
+  process.exitCode = await run(args, io);
+} else if (['news', 'session', 'deliver', 'skills'].includes(tool)) {
+  process.exitCode = await run([tool, ...args], io);
+} else if (tool === '--version' || tool === '-v') {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  console.log(pkg.version);
+} else {
+  console.log(`cadence — une méthode de travail qui vit dans le dépôt
+
+  cadence raf …     plan « reste à faire » relié aux commits (aussi disponible en « raf »)
+  cadence news …    Nouveautés : une entrée avec capture par lot visible, JSON + page autonome
+  cadence session start [--since "24 hours ago"] [--idle 2]
+                    faits de reprise : notes de la veille, en cours, fait depuis, écarts, propositions
+  cadence session close [--since …]    faits de clôture ; code 1 tant que ce n'est pas fermé
+  cadence session next "ligne" …       notes pour la prochaine session (sans argument : efface)
+  cadence deliver [--dry-run] [--config cadence.yaml]
+                    CI du sha poussé → déploiement → vérifications de l'effet
+  cadence skills install [--dir .claude] [--force]
+                    installe les skills Claude Code session-start, session-close, deliver et l'agent ux-reviewer`);
+  process.exitCode = !tool || ['help', '--help', '-h'].includes(tool) ? 0 : 2;
+}

package/bin/raf.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../dist/cli.js';
+
+process.exitCode = await run(process.argv.slice(2), {
+  cwd: process.cwd(),
+  env: process.env,
+  out: (l) => console.log(l),
+  err: (l) => console.error(l),
+  now: () => new Date(),
+});

package/dist/audit.js

@@ -0,0 +1,54 @@
+import { dirname, join, relative } from 'node:path';
+import { check } from './check.js';
+import { changedFiles, readCommits } from './git.js';
+import { linkCommits } from './link.js';
+import { loadEntries, newsIssues } from './news.js';
+import { isOpen } from './plan.js';
+/** Un commit qui ne touche que le plan (ou la page Gantt) n'a pas besoin de citer un lot. */
+export function exemptPlanOnly(linked, plan, root) {
+    const own = new Set([relative(root, plan.path), relative(root, join(dirname(plan.path), 'gantt.html'))]);
+    const orphans = linked.orphans.filter((c) => {
+        const files = changedFiles(root, c.sha);
+        return files.length === 0 || !files.every((f) => own.has(f));
+    });
+    return { ...linked, orphans };
+}
+/** Fenêtre de l'audit : --since, sinon la date d'adoption du plan, sinon 30 jours. */
+export function auditSince(plan, explicit) {
+    if (explicit)
+        return explicit;
+    // Une date seule vaudrait « ce jour-là à l'heure actuelle » pour git : minuit explicite.
+    return plan.since ? `${plan.since} 00:00` : '30 days ago';
+}
+/** Écarts entre le plan, l'historique et les Nouveautés — ce que `raf check` affiche. */
+export function audit(plan, root, newsDir, today, opts = {}) {
+    const lots = plan.lots();
+    const linked = exemptPlanOnly(linkCommits(lots, readCommits(root, { since: auditSince(plan, opts.since) }), plan.prefix), plan, root);
+    // L'inactivité se mesure sur tout l'historique, pas seulement la fenêtre --since.
+    const all = linkCommits(lots, readCommits(root), plan.prefix);
+    return [...check(lots, { ...linked, byLot: all.byLot }, today, opts.idle ?? 7), ...newsIssues(lots, loadEntries(newsDir), newsDir), ...uxIssues(plan)];
+}
+/**
+ * Lots visibles terminés APRÈS le jour d'activation sans revue UX enregistrée. Le jour même est exclu :
+ * à la journée près, on ne distingue pas un lot fermé avant l'activation d'un lot fermé après
+ * (et `raf done` refuse de toute façon dès l'activation).
+ */
+export function uxIssues(plan) {
+    const since = plan.uxSince;
+    if (!since)
+        return [];
+    return plan
+        .lots()
+        .filter((l) => l.visible && l.status === 'done' && !l.ux && (!l.finished || l.finished > since))
+        .map((l) => ({ message: `${l.id} est visible et terminé sans revue UX — raf ux ${l.id} "verdict"` }));
+}
+/** Ce qui vient ensuite : lots en cours, puis lots prêts (dépendances closes), gains rapides d'abord. */
+export function nextUp(lots) {
+    const byId = new Map(lots.map((l) => [l.id, l]));
+    const doing = lots.filter((l) => l.status === 'doing');
+    const ready = lots
+        .filter((l) => l.status === 'todo' && l.after.every((d) => !byId.has(d) || !isOpen(byId.get(d).status)))
+        .sort((a, b) => Number(b.quickwin) - Number(a.quickwin));
+    const blocked = lots.filter((l) => l.status === 'todo' && !ready.includes(l));
+    return { doing, ready, blocked };
+}

package/dist/check.js

@@ -0,0 +1,60 @@
+import { diffDays } from './dates.js';
+import { isOpen } from './plan.js';
+const short = (c) => `${c.sha.slice(0, 7)} ${c.subject}`;
+export function check(lots, linked, today, idleDays = 7) {
+    const issues = [];
+    const ids = new Set(lots.map((l) => l.id));
+    for (const c of linked.orphans)
+        issues.push({ kind: 'orphan-commit', message: `commit sans lot : ${short(c)}` });
+    for (const u of linked.unknown) {
+        issues.push({ kind: 'unknown-ref', message: `${u.ref} inconnu, cité par ${short(u.commit)}` });
+    }
+    for (const lot of lots) {
+        const commits = linked.byLot.get(lot.id) ?? [];
+        if (lot.status === 'todo' && commits.length > 0) {
+            issues.push({ kind: 'todo-with-commits', message: `${lot.id} a ${commits.length} commit(s) mais est encore todo — raf start ${lot.id}` });
+        }
+        if (lot.status === 'doing') {
+            const last = commits[0]?.day ?? lot.started;
+            if (last && diffDays(last, today) > idleDays) {
+                issues.push({ kind: 'idle', message: `${lot.id} en cours sans commit depuis ${diffDays(last, today)} j (${lot.title})` });
+            }
+        }
+        if (lot.status === 'done') {
+            const open = lot.tasks.filter((t) => isOpen(t.status));
+            if (open.length > 0) {
+                issues.push({ kind: 'done-open-tasks', message: `${lot.id} terminé avec sous-tâche(s) ouverte(s) : ${open.map((t) => t.id).join(', ')}` });
+            }
+        }
+        for (const p of lot.problems)
+            issues.push({ kind: 'bad-field', message: `${lot.id} : ${p}` });
+        for (const d of lot.after) {
+            if (!ids.has(d))
+                issues.push({ kind: 'bad-dependency', message: `${lot.id} dépend de ${d}, absent du plan` });
+        }
+    }
+    for (const cycle of findCycles(lots))
+        issues.push({ kind: 'cycle', message: `dépendances circulaires : ${cycle.join(' → ')}` });
+    return issues;
+}
+function findCycles(lots) {
+    const deps = new Map(lots.map((l) => [l.id, l.after]));
+    const state = new Map();
+    const cycles = [];
+    const visit = (id, path) => {
+        if (state.get(id) === 'done')
+            return;
+        if (state.get(id) === 'visiting') {
+            cycles.push([...path.slice(path.indexOf(id)), id]);
+            return;
+        }
+        state.set(id, 'visiting');
+        for (const d of deps.get(id) ?? [])
+            if (deps.has(d))
+                visit(d, [...path, id]);
+        state.set(id, 'done');
+    };
+    for (const l of lots)
+        visit(l.id, []);
+    return cycles;
+}