Rename blueprints/ to kb/ and record the house rules #6

Open

justine wants to merge 5 commits from refactor/kb-rename into main

pull from: refactor/kb-rename

merge into: justine:main

justine:main

justine:fix/future-annotations-audit

justine:chore/outdated-target

Conversation 0 Commits 5 Files changed 17 +437 -102

justine commented 2026-08-16 23:49:21 -07:00

Owner

Copy link

Closes #5

What changed

Renamed blueprints/ to kb/. The directory was named when it held only source material mirrored from Karl Voit. It now also holds the project vision, the plugin architecture, and standing rules about how the work gets done — "blueprints" describes about a third of that. Renamed with git mv so history follows; all 38 references updated, including the issue template's Blueprint reference field, now Knowledge base reference.

Added kb/07-house-rules.md. Feedback stated in conversation has been applied once and then forgotten each time. It now lives in the knowledge base with the failure that prompted each rule:

Rule	Prompted by
No unnecessary comments	The same 8-line explanation above four import blocks, when tests already enforced it
No untested causal claims	Asserting pluggy's design, then blaming target-version for a formatter rewrite
Workarounds carry upstream citations	The pluggy #629 comment written from reading source, not docs
Negative findings need two methods	One grep for get_type_hints reported as "nothing resolves annotations"
Branch and review every change	Stated directly

CLAUDE.md now opens with a pointer to it, and states that new rules land there when you state one — not when I judge one worth recording.

Filename effect

None. No naming logic changed.

Constraints

• Read commands still mutate nothing

Verification

$ uv run tox
  license, lint, format, typecheck, pyright, test — all OK

OKF conformance re-checked after the rename: all 8 concepts carry a type, kb/index.md declares okf_version, and 0 bundle-relative or root-doc links are broken.

Closes #5 ## What changed **Renamed `blueprints/` to `kb/`.** The directory was named when it held only source material mirrored from Karl Voit. It now also holds the project vision, the plugin architecture, and standing rules about how the work gets done — "blueprints" describes about a third of that. Renamed with `git mv` so history follows; all 38 references updated, including the issue template's `Blueprint reference` field, now `Knowledge base reference`. **Added `kb/07-house-rules.md`.** Feedback stated in conversation has been applied once and then forgotten each time. It now lives in the knowledge base with the failure that prompted each rule: | Rule | Prompted by | |---|---| | No unnecessary comments | The same 8-line explanation above four import blocks, when tests already enforced it | | No untested causal claims | Asserting pluggy's design, then blaming `target-version` for a formatter rewrite | | Workarounds carry upstream citations | The pluggy #629 comment written from reading source, not docs | | Negative findings need two methods | One grep for `get_type_hints` reported as "nothing resolves annotations" | | Branch and review every change | Stated directly | **CLAUDE.md now opens with a pointer to it**, and states that new rules land there when you state one — not when I judge one worth recording. ## Filename effect None. No naming logic changed. ## Constraints - [x] Read commands still mutate nothing ## Verification ```console $ uv run tox license, lint, format, typecheck, pyright, test — all OK ``` OKF conformance re-checked after the rename: all 8 concepts carry a `type`, `kb/index.md` declares `okf_version`, and 0 bundle-relative or root-doc links are broken.

justine added 1 commit 2026-08-16 23:49:21 -07:00

Rename blueprints/ to kb/ and record the house rules ... 3c7e43d0e1

Closes #5

`blueprints/` was named when it held only source material mirrored from Karl
Voit. It now also holds this project's vision, its plugin architecture, and
standing rules about how the work gets done. "Blueprints" implies plans for
things not yet built, which describes about a third of the contents; `kb/`
describes all of it. Renamed with `git mv` so history follows, and every one
of the 38 references updated, including the issue template's field label.

Add kb/07-house-rules.md. Feedback stated in conversation — no unnecessary
comments, no untested causal claims, workarounds carry upstream citations,
negative findings need more than one search, every change goes through a
reviewed branch — has been applied once and then forgotten each time. Each
rule is recorded with the failure that prompted it, so the reasoning survives
alongside the instruction.

CLAUDE.md now opens by pointing at that document, and states that new rules
land there when Justine states one rather than when I judge one worth
recording.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018XhA69mkFRwmkhrDvRsQLW

justine added 1 commit 2026-08-16 23:56:44 -07:00

Add the voice rule to the house rules ... 25476681f1

Ref #5

Code is text that goes out under Justine's name, so the rules governing her
prose govern identifiers, docstrings, comments, and commit messages as well.
The `writing-as-justine` skill is the specification; the house rules now carry
its core and the Stoic reasoning underneath it, mapped from prose to code:
fewest necessary words becomes no comment restating the line below it, describe
rather than judge becomes plain names over editorial ones, show rather than
announce becomes no self-congratulating comments.

The mechanics apply unchanged. No em-dashes, Oxford comma, American spellings,
plain and subject-first docstrings, no epigrams or payoff tags, no hype, limits
admitted flatly.

Audited the existing code against the rule rather than only asserting it. Zero
British spellings, zero hype words, zero wind-up docstring openings, and the
only two em-dash characters are the literal glyph rendered in table output. The
rule then caught four em-dashes in this document and in CLAUDE.md, which are
now semicolons and colons.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018XhA69mkFRwmkhrDvRsQLW

justine added 1 commit 2026-08-17 00:09:09 -07:00

Add the ASCII house rule and enforce it in tests ... b49b1ea588

Ref #5

Write ASCII, always, unless the output specifically calls for something ASCII
cannot provide. The reason is the one behind the project itself: a filename
outlives the tool that wrote it, and non-ASCII survives fewer terminals, fonts,
locales, and filesystems than ASCII does.

The exception is narrow. A character is allowed when it is the content rather
than the decoration, or when a library owns the rendering. Rich's box-drawing
table borders qualify; a dash, an arrow, or an ellipsis does not.

Converted five instances in code: an ellipsis in a comment, a dash in the
unchanged-row column, an arrow in the stacked narrow-terminal layout, and the
two test assertions that matched them. Both layouts were re-rendered and read
the same. Converted twenty-eight lines of prose across the knowledge base and
CLAUDE.md, all em-dashes I had written, which the voice rule already forbade.

Add tests/test_house_rules.py so the rule is enforced rather than remembered.
It checks every source and documentation file, exempting the Box Drawing and
Geometric Shapes blocks that appear in pasted terminal samples. Verified by
reintroducing an em-dash, which fails both the ASCII check and the em-dash
check.

Correct the voice rule while here. It said to replace an em-dash with a
semicolon, and mechanically applying that produced ungrammatical sentences that
had to be repaired by hand. The replacement is chosen by grammar: a semicolon
only when both sides are independent clauses, otherwise a colon, parentheses, a
comma, or a full stop.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018XhA69mkFRwmkhrDvRsQLW

justine added 1 commit 2026-08-17 00:17:03 -07:00

Replace em-dashes with a plain hyphen rather than rewriting sentences ... eadc6edead

Ref #5

The voice rule told me to pick a replacement by grammar, which meant rewriting
sentences to fit the punctuation. A plain hyphen substitutes for an em-dash
directly and leaves the sentence alone, so it is the default.

Restores the original wording in twenty-six lines across the knowledge base and
CLAUDE.md, all of which had been reworded only to accommodate a semicolon or a
pair of parentheses. The appositive pairs read as written again: "photo
services - iPhoto, Picasa - where users lost", "defaults - "Documents",
"Pictures", "Music" - organize by content type".

The semicolon caution stays, since a semicolon still needs an independent
clause on both sides, but it is now a footnote to the hyphen rather than the
first instruction.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018XhA69mkFRwmkhrDvRsQLW

justine added 1 commit 2026-08-17 00:25:58 -07:00

Author commits as Claude Code rather than as Justine ... dd361d9045

Ref #7

Every commit on this repository was authored `Justine Akehurst`, including the
ones Claude wrote, with Claude's involvement recorded only as a
`Co-Authored-By` trailer. That trailer is unindexed free text in the message
body: invisible to `git blame`, to `git log --author`, and to the review
interface. Work written by Claude therefore read as work Justine wrote, which
is backwards for a reviewer and wrong in the audit trail.

Commits Claude writes now pass `--author`, giving git's native split between
the author who wrote the change and the committer who applied it. Verified that
`git blame` reports `author Claude Code` and `committer Justine Akehurst`.

The identity names the tool rather than the model, so attribution stays stable
as the model behind it changes. This commit is the first written under it.

A Forgejo account for `claude-code` is still needed so pull requests are opened
under that identity too. Account creation requires instance admin rights, which
the repo-scoped `tea` token does not have.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018XhA69mkFRwmkhrDvRsQLW

All checks were successful

Hide checks

PR / issue-link (pull_request) Successful in 2s

Details

CI / check (pull_request) Successful in 41s

Details

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin refactor/kb-rename:refactor/kb-rename

git switch refactor/kb-rename

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff refactor/kb-rename

git switch refactor/kb-rename

git rebase main

git switch main

git merge --ff-only refactor/kb-rename

git switch refactor/kb-rename

git rebase main

git switch main

git merge --no-ff refactor/kb-rename

git switch main

git merge --squash refactor/kb-rename

git switch main

git merge --ff-only refactor/kb-rename

git switch main

git merge refactor/kb-rename

git push origin main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

justine/fname!6

No description provided.