Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
18a80e8
fix(vendor): Rebuild `src/vendor/cigraph` exactly from upstream and `…
krlmlr Oct 15, 2026
6d66975
feat(series): Vendor igraph one upstream commit at a time, as duckdb-…
krlmlr Oct 15, 2026
a0c44c5
docs: Install the handbook, and document the vendoring series loop (#…
krlmlr Oct 15, 2026
809e79f
refactor: Rename algorithm-selection arguments to `algorithm` and mea…
schochastics Oct 15, 2026
ed9d226
fledge: Bump version to 2.3.3.9043 (#2952)
github-actions[bot] Oct 16, 2026
bfdd882
feat(series): Keep the `rcc2` store with its pruning, and fix the fir…
krlmlr Oct 16, 2026
9294aac
fix(series): Date the regenerated tree anew, so a same-size upstream …
krlmlr Oct 16, 2026
c4de911
fix(series): Put a fold's note after the upstream subjects, not above…
krlmlr Oct 16, 2026
ad7d959
feat: Vendor the C-docs roclet from igraph.r2cdocs (#2955)
krlmlr Oct 16, 2026
267cc39
fledge: Bump version to 2.3.3.9044 (#2963)
github-actions[bot] Oct 17, 2026
6872081
feat(series): Extend `main-dev` ten commits at a time, and put harnes…
krlmlr Oct 18, 2026
1a636b5
feat(series): Mint `main-dev`'s extension without pushing it, with `-…
krlmlr Oct 18, 2026
2bd728f
feat(series): Retire engine gates, and accept a test removed with its…
krlmlr Oct 18, 2026
2472f78
feat(series): Review a series' R side before any landing, with `serie…
krlmlr Oct 18, 2026
d224506
fix(each): Defer a commit the leg deadline kills instead of failing i…
krlmlr Oct 18, 2026
f8ccc51
feat(rcc): Add `rcc-drop.sh`, for verdicts the job decided rather tha…
krlmlr Oct 18, 2026
c384094
fix(series): Keep the series' flavor patch through a port's tooling s…
krlmlr Oct 18, 2026
dcd8de7
fix(series): Fail the glue gate in C on what GCC 14 rejects by defaul…
krlmlr Oct 18, 2026
ae5516c
fix(series): Fold with a copy of series-fold.sh, and check that every…
krlmlr Oct 18, 2026
3e81de6
perf: Skip the error-reporting setup in `igraph_match_arg()` for vali…
schochastics Oct 2, 2026
9e9eb44
Merge remote-tracking branch 'origin/main' into claude/issue-2788-sub…
krlmlr Oct 18, 2026
8d6649a
chore: Auto-update from GitHub Actions
krlmlr Oct 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
7 changes: 6 additions & 1 deletion .Rbuildignore
Original file line number Diff line number Diff line change
Expand Up @@ -63,13 +63,18 @@
^src/*\.gcda$
^src/*\.gcno$
^R/release\.R$
^BRANCHES\.md$
^scripts$
^\.claude$
^\.series-source$
^\.build$
^lifecycle$
^jarl\.toml$
^touchstone$
^handbook$
^experiments$
^\.handbook-ignore$
^\.handbook-source$
^CLAUDE\.md$
^man/dot-igraph.progress\.Rd$
^man/dot-igraph.status\.Rd$
^man/dot-extract_constructor_and_modifiers\.Rd$
Expand Down
11 changes: 11 additions & 0 deletions .claude/commands/docs/check.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
name: "Docs: Check"
description: Check documentation consistency. Handbook shape, links, derived documents, and backreferences.
category: Docs
tags: [docs, handbook, maintenance]
---

Check that the documentation system is still whole, by the rules [`handbook/meta/handbook/`](/handbook/meta/handbook/README.md) owns.

Use the Skill tool with `skill: docs-consistency`, and follow it: run its script, fix what it reports, then work the judgment checks.
Don't push or open a pull request unless asked.
12 changes: 12 additions & 0 deletions .claude/commands/handbook/update.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
name: "Handbook: Update"
description: Check this handbook against its source, cynkra/handbook-tools, and refresh the pointer leaves, rule file, skills, and check script carried from it, or install them for the first time.
category: Docs
tags: [docs, handbook, maintenance]
---

Check this handbook against the source [`handbook/meta/local/`](/handbook/meta/local/README.md) names, and refresh what is carried from it.

Use the Skill tool with `skill: handbook-update`, passing the user's argument, if any, as `args`: `install`, `update`, or `check`.
The default is `check`, then `update` on a yes, then the reading that settles the source's changes here.
Never commit and never push: the user reviews and commits.
82 changes: 82 additions & 0 deletions .claude/rules/prose-authoring.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
paths:
- "**/*.md"
- "**/*.Rmd"
- "**/*.qmd"
- "**/*.yaml"
- "**/*.yml"
---

<!--
derived_from:
- handbook/meta/authoring/README.md
- handbook/meta/style/README.md
- handbook/meta/handbook/README.md
- handbook/meta/forms/README.md

The declaration sits here rather than in the front matter above, which belongs
to Claude Code: only `paths` is documented there, and a shared file should not
rest on how an unknown key happens to be treated. The checks read it from
either place.
-->

# Writing prose in this repository

_Derived from [`handbook/meta/authoring/`](/handbook/meta/authoring/README.md) and [`handbook/meta/style/`](/handbook/meta/style/README.md),
which own the prose rules,
and [`handbook/meta/handbook/`](/handbook/meta/handbook/README.md) and [`handbook/meta/forms/`](/handbook/meta/forms/README.md),
which own the tree's.
Those pages are the authority,
and [`handbook/meta/local/`](/handbook/meta/local/README.md) is what this repository decides beyond them.
All of them are shared pages whose home is `cynkra/handbook-tools`, and this file is carried from there unchanged.
This is the short form, and it loads when you touch a file that carries prose.
Fix the leaf first and re-derive this, never the other way around._

## Before writing a sentence

Walk these in order and stop at the first that answers.

1. Is it a fact about how things work today? Intent belongs where the local page says intent lives; history belongs to git and the logs.
2. Is it true? Verify against the thing itself before writing, not after review.
3. Does another handbook leaf, a file header, or a reference page own it? Link it, never restate or paraphrase it.
4. Does an artifact already state it? Never re-enumerate what a file lists; state the principle that locates it.
5. Could a check state it instead? A trap that keeps happening deserves a guard, not a paragraph asking readers to remember.
A measurement too expensive to re-derive becomes an experiment record, linked from the leaf that leans on it.
6. Then write it, as short as it can be and stay correct, and leave a breadcrumb where the reader stands.

A behaviour that looks wrong rather than chosen is settled before the ladder:
a small fix beats a paragraph, and a real limitation is stated with the issue that will remove it.

## Writing the sentence

- Semantic line breaks: break at meaning boundaries, never mid-phrase, never a one-word line,
never a line starting with one word and a comma.
- Aim for 140 characters, and let meaning win where it will not fit.
- A line ends with a full stop unless it is a heading, a bold run-in, a list item name, or a colon introducing a list.
- Default to a bullet list; make a table earn its columns.
- Name the mechanism rather than the count, treat a default as a fact by naming the value and where it is set,
and never refer to anything by position.
- A comment says what the line does and names the leaf that says why;
it takes the code's line budget, and every rule here holds inside it.
- Link a provisional fact to the issue or proposal that will change it, as a full link.
- Cite the claim, not its label: a number from another page's table means nothing where it is read.
- The rules this repository adopts beyond these, an em dash ban among the usual ones, are on the local page.

## Where the file lives in the tree

- A fact belongs on exactly one handbook leaf.
If you are about to write a durable fact into a document outside `handbook/`, that is the signal to put it on a leaf and link it instead.
- Every document outside `handbook/` either declares its handbook sources in a `derived_from:` list
or carries a visible backreference to the node it serves.
The list sits in front matter, or in an HTML comment where the front matter belongs to another tool, as an issue template's does.
A document with neither is an orphan.
- Editing a document that declares `derived_from:` means editing its sources first, then re-deriving.
- Link a boundary once per page, and link the leaf that owns the fact rather than the node above it.
- Never number a living page; only an append-only artifact takes a number or a date in its name.
- Run `/docs:check` before you finish, and work the skill's judgment checks too when the change is substantial.

## Where these rules stop

A GitHub issue or pull request body takes reflowed paragraphs, because a single newline renders there as a visible break.
Structure is not prose: a YAML key, a path, and a command are what they are, and only the sentences around them follow these rules.
Generated files and anything vendored from a third party are nobody's to reformat: fix the generator or leave it alone.
100 changes: 100 additions & 0 deletions .claude/skills/docs-consistency/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
---
name: docs-consistency
description: Check that the documentation system is whole. Handbook pages in the right shape, links that resolve, derived documents newer than their sources, a backreference on every document outside the handbook, and the judgment those checks cannot make. Use when a change touches documentation of any kind (a handbook page, `AGENTS.md`, `CLAUDE.md`, `README.md`, a skill or command file, a derived document), and periodically as a sweep.
license: MIT
compatibility: Requires git and a POSIX shell. The script beside this file uses only git, awk, sed, and grep.
---

# Documentation consistency

*The enforcement arm of the handbook rules ([`handbook/meta/handbook/`](/handbook/meta/handbook/README.md)):
the checks that keep the documentation system whole.*

This skill is the entry point.
The mechanical half is one script beside it, and the judgment is the reading around the script's findings.
Run the script first, from anywhere inside the repository, and spend the reading time on what it cannot see.

## The mechanical half

```sh
.claude/skills/docs-consistency/scripts/check-handbook.sh
```

Every finding is one line: a tag, a path, and what is wrong, and the script exits non-zero when it printed any.
What each tag means is [`handbook/checks/`](https://github.com/cynkra/handbook-tools/blob/main/handbook/checks/README.md)'s where this skill lives in its source repository;
in a repository that carries it, the tag names the rule and the path names the file, which is enough to act on.
The em dash check is on by default; [`handbook/meta/local/`](/handbook/meta/local/README.md) says whether this repository keeps it,
and `.handbook-ignore` is where it is dropped, by path or altogether.
Two reports print only when named, and both feed the judgment below:

```sh
.claude/skills/docs-consistency/scripts/check-handbook.sh board # status, verification date, depth per page
.claude/skills/docs-consistency/scripts/check-handbook.sh lines # every deepen line, with its page
```

Exemptions are the repository's:
`.handbook-ignore` at the root skips a generated or foreign file in every check, or in the orphan or em dash check alone,
with the reason beside the pattern.

## The judgment

1. **Tree shape.**
The script proves every directory has a page and every child is listed.
It cannot tell whether a scope sentence still admits its children,
whether a principle on a node passes the three tests in [`handbook/meta/forms/`](/handbook/meta/forms/README.md),
or whether a node has started explaining.
Hold `ls -d handbook/*/*/` beside the root's child list, whose entries sketch each area's next level in prose,
to see a child the sketch skipped, since it reads fluently either way.

2. **Coverage.**
Every part of the repository a reader could have a question about is claimed by exactly one leaf.
Walk the top-level directories and the root files against the leaves' scope sentences and deepen lines.
Unclaimed surface is a finding, reported with a proposed leaf address:
a homeless topic raises no error, so full cover is a claim to audit, not one the tree's shape can enforce.
Where a topic seems homeless, ask first whether a node's *wording* excluded it rather than its design.

3. **Backreferences.**
The script reports a document with neither `derived_from:` nor a link into the tree.
It cannot tell whether the node a document points at is the one it serves:
a pointer at the root, or at an internal node whose leaf owns the fact, answers nothing.
Nor can it tell whether a document that merely points should be derived, because it has started restating what a leaf holds.
Any secondary document touched by the change under review carries its backreference; add it or flag it.
A script or a configuration carries one too, in a comment, and which file is a document is this skill's call rather than a pattern's.

4. **Entries.**
An entry restating what the experiment, issue, or proposal it links already holds is a second copy of a record
([`handbook/meta/authoring/`](/handbook/meta/authoring/README.md) says how long an entry is).
A leaf past 120 lines owes an answer to why it is still one topic.

5. **Deepen lines.**
Their promises must still be redeemable.
Check each issue a *drain* clause names against the tracker with whatever GitHub access the session has,
since a closed issue is drained or dropped and never left promised,
and each section a line names against the headings of the file it would absorb.

6. **External links.**
The script skips them.
Check the repository's own issue and pull-request links with whatever GitHub access the session has,
and treat an unreachable foreign domain as unverified rather than broken:
in a sandboxed session the proxy answers for anything off the allow-list, which says nothing about the link.

7. **Headers.**
Where an in-place index is generated from file headers, whether a header says what its file does is judged here,
and a weak one is fixed at the source file rather than patched in the index.

8. **Status.**
A `draft` page that has since been verified is flipped to `confirmed` with a `verified:` date.
A stale `verified:` date on a page whose facts have moved is worse than none.

## Report and repair

Apply the small fixes in the same change:
a broken or upward link, a child list out of step with its directory, a missing backreference,
a missing or misplaced deepen line, a stale derivation.
Report the structural findings instead of acting on them:
unclaimed surface, an internal node accreting prose, a leaf outgrowing its scope, a page restating what the leaf it links already says.
One summary at the end, no per-file chatter.

Derivation runs one way: a wrong derived document is fixed at its handbook source and re-derived, never patched in place.
The rules define, this skill enforces:
when the two disagree, [`handbook/meta/handbook/`](/handbook/meta/handbook/README.md) is the authority, and the fix lands there first.
Loading