geneseed 3.7.0 → 3.9.0

package/src/skills/develop.md

@@ -9,30 +9,30 @@ case where the seam is only known once the change is made.
 
 ## Procedure
 1. Orient on the project's own documentation for what you are about to touch
-   ({{DOCTRINE}} process 4), and confirm the actual starting state — the suite runs,
-   the baseline is green ({{LAW}} III). A red baseline is a [debug {{SKILL}}](debug.md)
+   ({{DOCTRINE:read-the-docs-first}}), and confirm the actual starting state — the suite runs,
+   the baseline is green ({{LAW:verify-before-asserting}}). A red baseline is a [debug {{SKILL}}](debug.md)
    task first, not something to build on.
 2. Agree the seams: name the public interfaces the tests will target and confirm
    them with the user when they are not obvious — no test is written at an
    unconfirmed seam. Testing effort belongs on critical paths and complex logic,
    not every edge.
-3. Pick the next **smallest slice** that advances the task ({{DOCTRINE}} craft 6), then
+3. Pick the next **smallest slice** that advances the task ({{DOCTRINE:smallest-viable-diff}}), then
    cover it:
    - *Seam known up front* — test-first. Write ONE failing test that pins the slice,
      specific about the expected output (for a bug, the test reproduces it). Run it
      and watch it fail **for the right reason** — a test that passes immediately, or
      fails on a typo, proves nothing.
    - *Seam only clear once the change exists* — write the covering test alongside the
-     change ({{DOCTRINE}} rigor 3), then break the implementation on purpose once to
+     change ({{DOCTRINE:cover-and-verify}}), then break the implementation on purpose once to
      see the test go red before trusting it.
 4. Write the minimum code that makes it pass; add nothing the test doesn't demand.
-5. Run the *affected* tests and read the output ({{LAW}} III); on failure fix the
-   cause, never mask it ({{LAW}} VIII). Dispatch the
+5. Run the *affected* tests and read the output ({{LAW:verify-before-asserting}}); on failure fix the
+   cause, never mask it ({{LAW:cure-the-cause}}). Dispatch the
    [tester {{AGENT}}](../{{DIR_AGENTS}}/tester.md) for heavier or unfamiliar coverage,
    or when the blast radius is unclear.
 6. With the slice green, tidy through the [refactor {{SKILL}}](refactor.md) — the tests
    are the safety net — then commit the slice through the [commit {{SKILL}}](commit.md)
-   ({{DOCTRINE}} process 5). Loop from step 3, one slice at a time.
+   ({{DOCTRINE:consent-before-push}}). Loop from step 3, one slice at a time.
 7. **Exit.** When the last slice is in: run the whole affected suite once more, state
    what was run and its result, and hand over — to the [ship {{SKILL}}](ship.md) when
    the change is ready for a PR, or to the [handoff {{SKILL}}](handoff.md) if the

package/src/skills/document-project.md

@@ -13,8 +13,8 @@ write; with none, step 3 proposes them.
    convention [repo-map {{SKILL}}](repo-map.md) and the context loader use). Reuse the one
    that exists — never create a second. If none exists, create `docs/` at the root.
 2. **Survey the code, not the intent.** Map entry points, the public API / modules,
-   commands, config, and key directories — read the actual behaviour (universal {{LAW}} III,
-   {{DOCTRINE}} process 4). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
+   commands, config, and key directories — read the actual behaviour ({{LAW:verify-before-asserting}},
+   {{DOCTRINE:read-the-docs-first}}). If there is no `ARCHITECTURE.md`, run [repo-map {{SKILL}}](repo-map.md)
    first so you have the orientation map to build on.
 3. **Select the doc set.** Unless the argument names the targets, propose which of the four
    documents apply and wait for the user's go-ahead — e.g. "no UI detected (no stylesheet,
@@ -30,7 +30,7 @@ write; with none, step 3 proposes them.
 5. **Reconcile the markdown (whole tree).** Check every existing page against the current
    implementation — renamed or removed APIs, changed flags, dead examples — and fix the
    drift. Add pages for significant undocumented surfaces; remove docs for features that no
-   longer exist (deletion is deliberate — {{LAW}} IV). For substantial writing, dispatch
+   longer exist ({{LAW:deletion-is-deliberate}}). For substantial writing, dispatch
    the [docs {{AGENT}}](../{{DIR_AGENTS}}/docs.md). Keep examples runnable — run them.
    Every generated page follows three conventions:
    - **Typed frontmatter.** Open each page with YAML frontmatter carrying `type:` (one of
@@ -52,9 +52,9 @@ write; with none, step 3 proposes them.
    members included, current with the set you just reconciled.
 7. **Regenerate the HTML** — self-contained files at the doc home, a visual parallel to the
    markdown and never a source of truth: regenerate them whole from the markdown each run
-   ({{DOCTRINE}} ops 3: edit the source, not the surface).
+   ({{DOCTRINE:edit-the-source-not-the-surface}}).
    Overwrite the previous ones, but confirm each is the generated artifact before clobbering
-   ({{LAW}} III, {{LAW}} IV). Both files:
+   ({{LAW:verify-before-asserting}}, {{LAW:deletion-is-deliberate}}). Both files:
    - **Stand alone, fully offline** — a single file, content pre-rendered to semantic HTML,
      all styling in one inline `<style>`, at most minimal vanilla JS (light/dark toggle, TOC
      scroll). No CDN, no external assets, no web fonts (use a system-font stack). Render any
@@ -84,7 +84,7 @@ write; with none, step 3 proposes them.
    (variants, states, path) — no live rendering, which would need the project's framework; and
    the hard-coded-value drift in a separate callout.
 8. **Do not auto-publish.** Leave the changes for the user to review; stage and commit only
-   on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE}} process 5).
+   on consent, via the [commit {{SKILL}}](commit.md) ({{DOCTRINE:consent-before-push}}).
 
 ## The doc set
 

package/src/skills/explain-changes/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: explain-changes
+description: "Explain a change visually before it is committed: renders one offline HTML page — the intent, the risks to check first, a walkthrough by logical unit, and the exact git diff side by side — and opens it. Use when the user asks to explain, walk through, show, visualise or review the changes ('what did you change?', 'show me the diff'), before asking consent to commit a non-trivial change (offer it, never impose it), or to explain a whole branch or PR."
+---
+
+# explain-changes
+
+> Turn a diff into a page a human can actually verify: why each part changed, what to check first, and the exact diff beside it.
+
+**Trigger:** the user asks to explain, walk through, show or visualise the changes; you are about to ask consent to commit a non-trivial change (offer the report — never make it a condition); or the user wants a branch or PR explained (`--base <ref>`).
+
+## Division of labour
+
+You write the **brief** — the narrative only. `scripts/render_changes.mjs` runs `git diff` itself and puts the exact diff on the page. Never paste diff lines into the brief: you would pay for them in output tokens and could alter the very thing under review. The script only reads git; it never stages anything.
+
+## Procedure
+
+1. **Measure.** `git diff --cached --shortstat`; if empty, `git diff HEAD --shortstat`; for a branch, `git diff <ref>...HEAD --shortstat`. The shortstat leaves out untracked files, which the report includes when nothing is staged: add `git ls-files --others --exclude-standard | wc -l` (or the host equivalent) to the file count.
+2. **Choose who writes the brief.**
+   - You made the change, and it is under ~300 changed lines and ~10 files: write it yourself from what you already know. Read only the hunks you do not remember (`git diff -- <path>`).
+   - Bigger, a change you did not make, or your context is already heavy: delegate to **one fresh subagent** (the `developer` agent where the host has agents). Hand it the user's request verbatim, your intent notes per logical unit (a few lines each), the diff command, this file's brief rules, and the render command. It returns the report path and three lines. The full diff never enters your context.
+   - No subagents on this host: write the brief one logical unit at a time, reading `git diff -- <paths>` for that unit only.
+3. **Write the brief** as JSON to a temporary file outside the repository (schema below).
+4. **Render.**
+   `node <this-skill-directory>/scripts/render_changes.mjs --brief <brief.json> --out <your notebook directory>` — add `--base <ref>` for a branch. Your notebook directory is named in your root instructions; if this install has none, omit `--out` and the report goes under `.git/explain-changes/`.
+   `--base <ref>` covers committed work only (`<ref>...HEAD`); uncommitted changes are not in it — commit first, or explain them separately without `--base`.
+5. **Fix mismatches.** If the script prints narrative mismatches — a file or hunk you cited that is not in the diff, a changed file no unit explains, an unsafe diagram, no risks — fix the brief and re-run. Never hand over a bannered report.
+6. **Open it.** Windows `start "" "<path>"` from cmd or Git Bash, `Start-Process "<path>"` from PowerShell; macOS `open "<path>"`, Linux `xdg-open "<path>"`. If that fails (headless, SSH, container), print the path instead.
+7. **Hand over** in two lines: the path, and the one risk the user should check first. Before you later ask commit consent, run the script with `--hash`: if it differs from the `diff <hash>` in the report's footer, the diff has changed since — regenerate.
+
+## The brief
+
+```json
+{
+  "lang": "en",
+  "title": "HTTP cache with expiry",
+  "request": "the user's request, verbatim",
+  "summary": "3-5 sentences: what changes for the user or the system, and why",
+  "risks": [
+    { "level": "high", "text": "The cache key ignores auth headers: two users can get each other's response.", "unit": "u2" }
+  ],
+  "units": [
+    {
+      "id": "u1",
+      "kind": "entry point",
+      "title": "The client reads the cache before the network",
+      "why": "1-2 sentences",
+      "files": ["src/http/client.js"],
+      "hunks": { "src/http/client.js": [0, 1] },
+      "out_of_scope": false,
+      "svg": "<svg viewBox=\"0 0 760 150\">…</svg>"
+    }
+  ]
+}
+```
+
+- `request` is the user's words, verbatim — not your summary of them.
+- **Units follow execution order** (entry point → core → effects → tests), not file order. One unit = one intent. `hunks` picks hunks by index; omit it to show every hunk of each file in `files`.
+- **`risks` is the section the reader acts on.** Cover, whenever they exist: assumptions you did not verify; what is untested; files touched outside the request (also mark that unit `"out_of_scope": true`); user-visible behaviour changes (API, config, schema, migrations). You are describing your own work — err toward listing. `level` is `high`, `medium` or `low`. An empty list needs `"risks_none_reason"`.
+- **`svg` only when the change alters a flow between components** — a call sequence, a data model, a state machine. A change local to one file gets none. Hand-written inline SVG, one `<svg>` element and nothing after it; no scripts, event handlers, `foreignObject`, `<style>` (use attributes), animated links, external links or `url()` to anything but a `#fragment` — the script drops unsafe diagrams. Use `currentColor`, `var(--muted)`, `var(--add-ink)`, `var(--del-ink)`, `var(--line)` and `var(--code-bg)` so it follows the page theme.
+- `lang` is `en` or `fr`, matching the user's language; write every text field in that language.
+
+## Privacy
+
+The report contains code. It stays in a git-ignored local path; if the diff holds a secret, the report does too — the same exposure as the diff itself. Never commit or publish a report.
+
+## Done when
+
+- A report built from the current diff exists with no mismatch banner, it is open (or its path given), and the user knows the one risk to check first.

package/src/skills/explain-changes/VENDOR.md

@@ -0,0 +1,20 @@
+# Folder skill — explain-changes
+
+Like `token-report`, this folder is **Geneseed-authored**, not third-party. It rides
+the vendored-folder mechanism because it bundles an executable
+(`scripts/render_changes.mjs`) and Geneseed's flat-skill pipeline renders single
+`.md` files only. Listing it in the generator's `VENDORED_SKILL_DIRS` makes the
+whole folder ride along verbatim into every host emit — Claude Code, IBM Bob,
+OpenCode, GitHub Copilot, OpenClaude.
+
+- **Upstream:** this repository (first-party)
+- **License:** same as Geneseed (see repository LICENSE)
+
+Consequences of riding this mechanism (deliberate):
+
+- exempt from the flat-skill authoring gates (theme DESC tokens, dead-link,
+  hermeticity) — the SKILL.md carries its own frontmatter `description`, and it
+  names no themed term: the notebook directory reaches the script as `--out`;
+- listed in AGENT.md's folder-skills section, not the main skills table.
+
+The script needs only `node` and `git`, both already present wherever Geneseed runs.