proctolog 0.1.0

data/public/words.js

@@ -0,0 +1,81 @@
+// The words of a description, as the desk and the server count them.
+//
+// A section's text is that of GitHub's nodes alone, and a note quotes it with
+// a little before and after. What the desk puts inside a section is marked
+// data-desk and left out here as Rendering leaves it out there: the + beside
+// a block, the form of a note, the notes under a box. So a note quotes the
+// same words whether or not the desk has added anything.
+
+const NEAR = 64;
+
+// What a note can be pinned to without selecting anything: a paragraph, a
+// list item, a heading, a table row, a code block, a caption, a picture.
+export const BLOCKS =
+	"p, li, h3, h4, h5, h6, pre, tr, dt, dd, figcaption, figure.picture";
+
+export const elementOf = (node) =>
+	node.nodeType === Node.TEXT_NODE ? node.parentElement : node;
+
+export const inDesk = (node) => elementOf(node).closest("[data-desk]") !== null;
+
+// The block of the description that holds a node, if it is GitHub's.
+export const blockOf = (node) => {
+	const block = elementOf(node).closest(BLOCKS);
+	return block && !inDesk(block) ? block : null;
+};
+
+export const blocksIn = (node) =>
+	[...node.querySelectorAll(BLOCKS)].filter((block) => !inDesk(block));
+
+// The text of a copy, without the desk's own elements.
+export const measured = (copy) => {
+	for (const own of copy.querySelectorAll("[data-desk]")) own.remove();
+	return copy.textContent;
+};
+
+// A block's own sentence: its words up to the first block inside it, so that
+// a list item with a list under it is noted for what it says itself.
+export const ownWords = (block) => {
+	const range = document.createRange();
+	range.selectNodeContents(block);
+	const [inner] = blocksIn(block);
+	if (inner) range.setEndBefore(inner);
+	return range;
+};
+
+export const hasWords = (block) =>
+	measured(ownWords(block).cloneContents()).trim() !== "";
+
+// Stops a quote's edges from cutting a character in two.
+const clean = (text) => text.replace(/^[\uDC00-\uDFFF]|[\uD800-\uDBFF]$/g, "");
+
+// The words a range covers, as a note holds them: the words themselves, and
+// the text around them in their section. The offset is a count of characters
+// of the section's own text, so it is the same however the page is laid out.
+// Null when the range is not within one section, or touches the desk's own.
+export const quoteOf = (range) => {
+	if (inDesk(range.startContainer) || inDesk(range.endContainer)) return null;
+	const body = elementOf(range.commonAncestorContainer).closest(
+		"[data-quotable]",
+	);
+	if (!body) return null;
+
+	const lead = document.createRange();
+	lead.selectNodeContents(body);
+	lead.setEnd(range.startContainer, range.startOffset);
+
+	const picked = measured(range.cloneContents());
+	const start =
+		measured(lead.cloneContents()).length +
+		(picked.length - picked.trimStart().length);
+	const exact = picked.trim();
+	const text = measured(body.cloneNode(true));
+	if (!exact || text.slice(start, start + exact.length) !== exact) return null;
+
+	return {
+		exact,
+		before: clean(text.slice(Math.max(0, start - NEAR), start)),
+		after: clean(text.slice(start + exact.length, start + exact.length + NEAR)),
+		section: body.dataset.section,
+	};
+};

data/skills/proctolog-handover/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: proctolog-handover
+description: Take the owner's review from PRoctolog, the review desk on their Mac, and carry it out - their notes, their choices on the decisions and their code comments, handed over with `proctolog handover` from the checkout under review, even halfway through the review, and answered in the one file the desk reads back. Use when the owner names PRoctolog or its desk - "check my proctolog comments", "check my proctolog notes", "do what I decided in proctolog", "pick up my proctolog review" - when they say "check again" after an earlier pass of this skill, or when they give you a PRoctolog handover folder or its handover.md. Not for review comments on GitHub alone.
+---
+
+# Taking the owner's review from PRoctolog
+
+The owner reviews pull requests on PRoctolog, a desk on their Mac. What they
+decide there (a change, a question, a task for later, a rule) waits for an
+agent. You take it yourself; nobody needs to press anything.
+
+## Take a pass
+
+From the checkout of the repository under review:
+
+```sh
+proctolog handover
+```
+
+It hands over everything the owner decided that no agent has yet, writes it as
+a folder where the desk keeps handovers, and prints what went in and where the
+brief is. `proctolog burst list` names the bursts when there are several:
+`proctolog handover first-run`. `--part 1055` takes one part of a burst alone,
+when the owner names one.
+
+When it says nothing waits, tell the owner so, and stop. When it says the
+checkout has no burst, or is no checkout at all, PRoctolog is not used here:
+say so, and stop.
+
+## Work through it
+
+Read the brief, `handover.md`, whole. Its rules are the owner's and bind you,
+beside the repository's own. Then read one pull request's file under `prs/` at
+a time, from the bottom of the stack up. `worklist.json` holds the same
+requests as data.
+
+The owner may be halfway through their review, and may go on while you work.
+Change nothing the worklist does not name: not a description's other
+decisions, their keys or their pictures. A decision they have not reached yet
+is no instruction.
+
+Writing a description goes by the `proctolog-pr-writing` skill. Every write to
+GitHub waits for the owner's word, as the brief's rules say. A pull request
+nobody has opened yet is described in a file on this Mac, which its layer's
+file names: rewrite that file in place, front matter kept, and open nothing.
+
+## Answer
+
+Write the one file the brief names, under the burst's `responses/` folder, in
+the format `proctolog-response/v1`. Write it even when you cannot finish: give
+what you could not do as blocked, and say why. Until an answer comes back, the
+desk holds that pass's requests back from every later one. Write nothing else
+under the desk's folders: the marks and choices are the owner's.
+
+To correct an answer, after a restack or a fix, write the same file again with
+the time of writing as its `createdAt`. The desk shows the new version and
+keeps the one before.
+
+The desk shows your answers to the owner, who confirms each one or replies.
+
+## Held back
+
+The command may say that requests an earlier pass handed over are still with an
+agent that has not answered. They are held back so that two agents never do the
+same work. Take them only when the owner says no agent is at them, or tells you
+to take everything they decided:
+
+```sh
+proctolog handover --again
+```
+
+When you cannot ask, leave them, and say so in your last message.
+
+## Check again
+
+When the owner says to check again, run `proctolog handover` once more. It
+carries only what they decided since, and their replies to your answers.

data/skills/proctolog-pr-writing/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: proctolog-pr-writing
+description: Write, rewrite or regrade pull request descriptions for PRoctolog, the review tool - decisions for the owner graded blocking or non-blocking, each with a theme, at most five blocking, checked with `proctolog check` before the owner publishes them - including for branches nobody has opened yet, which the desk reviews from a folder on this Mac. Use whenever asked to "write these PRs for PRoctolog", "rewrite this PR's description for PRoctolog", make PRs reviewable in PRoctolog, review work on PRoctolog "without opening PRs" or "before opening PRs", grade a description's decisions or prepare one for review on PRoctolog, or open on GitHub what was reviewed unopened. Every GitHub write waits for the owner's word. Working through the owner's review is the proctolog-handover skill.
+---
+
+# Writing a pull request for PRoctolog
+
+The owner reviews this work on PRoctolog, a desk that reads each description,
+lists its decisions, asks the owner about each, and hands the answers back to
+an agent. A description is written for that reading: what was built, what the
+owner must decide, and how to see it. The diff is on GitHub already; say what
+it cannot.
+
+Start from compound-engineering's guide to PR descriptions
+(`ce-commit-push-pr/references/pr-description-writing.md`): lead with what is
+now possible or fixed, never with what files moved, and size the description
+by what it costs the owner to decide, not by the size of the diff. What
+follows is what the desk adds to that.
+
+A complete example is in `references/example-description.md`.
+
+## The sections
+
+Keep the project's own template (Summary, Changes, Verification) and add these,
+with exactly these second-level headings:
+
+- `## How to test locally`: a **bold scenario name** over numbered steps, each
+  step one line: "Do this. Expect that." The desk opens each scenario from the
+  bold name.
+- `## Decisions for the owner`: what the owner decides. Each decision is one
+  task item on one line.
+
+## What is a decision
+
+Use the feedback ladder (Netlify's):
+
+- **Mountains and boulders are blocking.** A choice that loses data, changes
+  who can do what, costs money, breaks an agreed rule, or cannot be undone
+  cheaply; or one the owner should settle before the work goes. These stay at
+  the top of the section.
+- **Pebbles are non-blocking.** A choice a sensible default settles, which the
+  owner may still want to see: a wording, a spacing, a fold. They go under a
+  `### Non-blocking` heading, after every blocking decision.
+- **Sand and dust are no decisions.** Implementation facts belong in Changes;
+  test gaps in Verification under "Not verified"; the rest nowhere.
+
+**At most five blocking decisions.** More than five asks too much of one owner
+at once: grade the ones a default can settle non-blocking, split the work, or
+settle what a rule already settles (below). The desk warns past five.
+
+The desk asks the blocking decisions one by one. The owner can leave every
+non-blocking decision that waits for nothing as it is, in one gesture, so a
+non-blocking decision must be one the owner could leave and not regret.
+
+## The decisions section
+
+```markdown
+## Decisions for the owner
+
+- [ ] **Verifying can delete an account row.** Why it was built so, and who it affects. See [the row](#screenshot-account-row). Alternative: refuse instead, at the cost of a stuck account. <!-- proctolog:theme accounts -->
+
+### Non-blocking
+
+- [ ] **"Skip for now" sits under a 664px fold.** Why. Alternative: tighten the step. <!-- proctolog:theme fit -->
+```
+
+Each decision:
+
+- is one line, a top-level task item: `- [ ] ` and nothing indented under it;
+- opens with what was built, in **bold**: a distinct lead, which is how the
+  desk knows the decision again after an edit;
+- says why, and who it affects;
+- links the pictures that show it, beside the claim: `[a label](#screenshot-NAME)`,
+  where NAME is one picture's exact, unique `alt` text in this description;
+- names the alternative last in its words: `Alternative: …`, with its cost, or
+  `Alternative: none.` when there is none worth offering;
+- ends with its theme: `<!-- proctolog:theme NAME -->`.
+
+The heading `### Non-blocking` is visible on GitHub on purpose: the grade
+matters to anyone reading the pull request there.
+
+## Themes
+
+A theme says what kind of question a decision asks, so the owner can answer one
+kind across the burst at once. Use one of the project's: `proctolog themes`
+prints them with what each means. The desk's own list, which a project may
+replace in `.proctolog/project.yml`:
+
+| Theme | What it covers |
+|---|---|
+| `copy` | What the words on a screen say, and how |
+| `fit` | How a screen holds what is on it: wrapping, folds, sizes |
+| `errors` | What happens when something fails, and what the member is told |
+| `accounts` | Who a member is: signing up, signing in, their account |
+| `data` | What is kept, moved or deleted, and who may see it |
+| `plan` | What was built against what was planned |
+| `build` | How the code is made: its parts, its dependencies, its tools |
+| `limits` | Bounds: sizes, counts, rates and time |
+
+The marker is hidden on GitHub and is no part of the decision's words: adding
+or mending a theme never reopens a choice the owner made.
+
+## References: keep them, never invent them
+
+A new decision carries no reference. When you rewrite a decision the owner
+already answered, keep its handover's `source.decision.key` as a hidden marker
+right after the bold lead, `<!-- proctolog:decision KEY -->`, so the owner's
+choice follows it. Never give a reference to a new decision, and never reuse
+one for another. Drop a decision the owner settled from the active list when
+the work no longer needs it; its history stays on the desk.
+
+## Rules already made
+
+When a rule the owner already made settles a choice (in the project's
+`CLAUDE.md`, a decision record, or a burst's rules), do not list it as a
+decision. Say in Changes which rule settled it: "Dates are the member's own day
+(CLAUDE.md, Dates)." A decision that contradicts a rule is blocking, and says
+which rule.
+
+## Evidence: fewer pictures, each one linked
+
+A picture is evidence for a claim, so it belongs beside the claim it shows.
+
+- **Take a change as a pair.** Shoot the same screen before the change and
+  after it, named `NAME-before` and `NAME-after` (the capture kit's `before
+  "NAME"` and `after "NAME"`, with `integrations/sartoria/compare.rb` required
+  after `kit.rb`). Upload both halves as they are, never composed side by side:
+  the desk joins them into one picture with its own compare views, and a
+  decision links the pair as `#screenshot-NAME`.
+- **Compare before uploading.** `Capture.compare(names, out:)` drops a pair
+  whose pixels did not change, groups pairs of one size that show the same
+  change, and writes `compare.json`. Upload only what its `upload` list names:
+  one pair of a group stands for the others, which the description need not
+  show.
+- **Link every picture** from a decision or a step of a scenario. The desk
+  folds a run of pictures nothing links under "More pictures (N)"; one that
+  matters is linked.
+- Uploading is a write to GitHub: it goes in the owner's authorized batch, with
+  the rest.
+
+## Check before asking
+
+Write the description to a file and check it with the desk's own parser:
+
+```sh
+proctolog check --file body.md
+```
+
+It exits 0 when the desk reads it well, 1 with faults (each on its line), and 2
+when GitHub could not be asked. GitHub renders the file for the check and keeps
+nothing of it. Mend every fault; weigh every warning. A picture link resolves
+only to a picture already uploaded to GitHub, so check again once pictures are
+in place.
+
+A published description can be checked as GitHub holds it: `proctolog check 1062`.
+
+## GitHub writes wait for the owner
+
+Every write to GitHub waits for the owner's word in that session: an edit of a
+description, an upload of a picture, a push, a comment, a label. Prepare the
+description, check it, show it, and wait. Never edit a description the owner
+marks as another session's (the burst file's `hands_off`).
+
+## Not opened yet
+
+When the owner wants the work reviewed before any pull request is opened,
+write each one where the desk reads it instead of on GitHub. One branch, one
+pull request, as `gh pr create` would be told it, in the folder
+`proctolog unopened folder BRANCH` prints:
+
+```markdown
+---
+title: A reset mail says which account it is for
+base: recovery/fields
+---
+## Summary
+…
+```
+
+- `pull_request.md` holds the title and the base as front matter, then the
+  description, written as everything above says. The base is the branch it
+  goes into: `main`, or the branch of the layer under it. Layers may be built
+  with `gh stack init` and `gh stack add`; never `gh stack submit` until the
+  owner says to open them.
+- Pictures go beside it, named as their alt text and linked by their file
+  names: `![reset-mail-after](reset-mail-after.png)`. Pairs are
+  `NAME-before.png` and `NAME-after.png`, compared as above. Nothing is
+  uploaded.
+- Check each with `proctolog check BRANCH`: it reads the folder, pictures and
+  all. `proctolog unopened` lists those the desk reads, each with its number,
+  01, 02, which the desk gives them.
+- A burst names them by their branch, so it still holds them once they are
+  opened. Make it yourself, as part of the work: `proctolog burst new NAME
+  --top BRANCH` for a chain, `--pr BRANCH` for one alone. Never hand the
+  owner that step. They run `proctolog serve` in the repository or any of its
+  worktrees, which share the store, and find the burst on the desk.
+
+Writing these files is no write to GitHub: rewrite them as a handover asks
+without waiting for the owner's word. Keep the front matter as it is.
+
+## Opening what was reviewed
+
+Only when the owner says to. Opening is a GitHub write, in the owner's
+authorized batch:
+
+1. Push the branches.
+2. Upload the pictures, and change each link to the uploaded address, its alt
+   text as it was.
+3. Open each from the bottom up, with its own title, base and description:
+   `gh pr create --head BRANCH --base BASE --title TITLE --body-file FILE`,
+   the file being `pull_request.md` without its front matter. Or
+   `gh stack submit`, then `gh pr edit NUMBER --body-file FILE` for each.
+4. `proctolog check NUMBER` each.
+
+The desk notices each opened branch on its next reading, and carries the
+owner's review over to the new number. Decision keys must survive the move
+unchanged, or the owner's choices do not follow them. Leave the folders as
+they are: the desk no longer reads them once their branch is opened.
+
+## Answering a handover
+
+The owner's answers come back to you as a handover, which the
+`proctolog-handover` skill takes and answers: `proctolog handover` hands over
+what they decided, even halfway through. The answer is one
+`proctolog-response/v1` JSON file, in the folder the brief names. Its schema is
+`../../public/schemas/proctolog-response-v1.json` from this skill's folder.
+Answer only the request ids the handover gives; the desk refuses invented ones.
+A rewritten description goes through everything above again, references kept.

data/skills/proctolog-pr-writing/references/example-description.md

@@ -0,0 +1,33 @@
+## Summary
+
+A member who signs in with a passkey now lands where they were going, not on the home page. Before, every passkey sign-in dropped the page they had asked for; a member who followed a link to a house had to find it again.
+
+## How to test locally
+
+**Back to the page asked for.**
+1. Sign out, then open a house's page. Expect the sign-in page.
+2. Sign in with a passkey. Expect the house's page, not the home page.
+
+**No page asked for.**
+1. Sign out, then open the sign-in page itself. Expect the sign-in page.
+2. Sign in with a passkey. Expect the home page.
+
+## Changes
+
+- The passkey sign-in keeps the page asked for, as the password sign-in already did.
+- A page asked for is kept for ten minutes, as the password sign-in keeps it (CLAUDE.md, Sessions), so it is no decision here.
+
+## Decisions for the owner
+
+- [ ] **A page asked for on another site is dropped, and the member lands on the home page.** A link from outside cannot send a member anywhere after they sign in; it affects members who follow links from email. Alternative: keep such a page when it is on this site's own domain, at the cost of a check that can be got wrong. <!-- proctolog:theme accounts -->
+- [ ] **A member who signs in on a second device keeps the page asked for on that device alone.** Each device keeps its own; a member who starts on a phone and signs in on a laptop lands on the laptop's home page. Alternative: keep it with the account, which needs a column and a migration. <!-- proctolog:theme data -->
+
+### Non-blocking
+
+- [ ] **The sign-in page says "Continue with a passkey".** As the password button's "Continue" does. Alternative: "Sign in with a passkey". <!-- proctolog:theme copy -->
+
+## Verification
+
+- `bin/rails test test/controllers/passkey_sessions_controller_test.rb`: 9 runs, 0 failures.
+
+Not verified: a passkey on a second device, by hand.