docs(kvb-check-score): move tables and journal into side files

Requirement 006 grew SKILL.md to 853 words, over the 600-word cap test_lock enforces. The tables and message block details move to tables.md and the score journal with its backfill to journal.md; SKILL.md keeps the commit-block rule and points to both. The journal reader set in test_score_journal follows the text to journal.md.

🎯 Fix: 95 %
💥 Break: 2 %
💸 Cost: 110 %
⏱️ Time: –
🛡️ Security: ~100 %
🏆 Score: 85
🚦 Gate: ⚠️ cost 110 % > 100: ask the operator before the commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-13 16:11:47 +00:00
1 parent ca9cd96442
commit c8384e01d6
4 files changed
+52 -41

No files matched your search

+7 -40
View File
@@ -58,46 +58,13 @@ The second line is the verdict, first match wins:
## Tables and message block
Each flag replaces the two lines; values, gate and exit code stay:
- `--table`: one markdown table, `| 🎯 Fix | 💥 Break | 💸 Tokens |
⏱️ Velocity | 🛡️ Security | 🏆 Score | Gate |`.
- `--commit-table <repo>`: that table led by `🌿 Branch | 📊 Diff stat`
from git, 📁 worktree path below, alone in a code block. Every commit
block is this table; after the commit, `--commit <sha>` shows that commit's diff stat
and a `🔖 Commit` column.
- `--message-block`: one value per line, `🎯 Fix: <f> %` through
`🏆 Score: <n>` and `🚦 Gate: <verdict>`. Every commit message carries it
as its own paragraph right before the `Co-Authored-By` line, passed as one
`-m` argument, so the approval prompt and git history show the values.
On a skill change add `--value <n:n|?>`, the quotient of the 💰 line (`?`
while it has no value): a `💰 Value` column after `💸 Tokens`, or line
after `🛡️ Security`. It changes neither score nor gate; alone it is a usage
error.
Every commit block is the `--commit-table` and every commit message carries
the `--message-block` paragraph right before the `Co-Authored-By` line.
Read `tables.md` next to this file before using `--table`,
`--commit-table`, `--message-block` or `--value`.
## Journal
Each `--message-block` render appends one row to
`${AGENTS_COUNCIL_ROOT:-/tmp/agents-council}/scores.jsonl`: time, origin
remote, top level path, branch, `sha` null, the six values and the block's
digest. The hub's burndown draws it as overlays; no gate reads it. A failed
append prints one stderr line and keeps the exit code; a linked council
root or a link, FIFO or other non-regular file at the journal fails it
without blocking, through `nofollow.py` of `kvb-org-organize`; when that
helper is missing or unusable, the line names it. A new council root gets mode
0700, a new journal 0600.
The journal lives in `/tmp`, so a reboot or another PC starts empty. Refill
it from the blocks in git history, without a model:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/backfill.py --repo <dir>... [--since <rev>] [--labels <file>]
```
It reads every local and origin branch, takes the last block of each commit
message, old labels included, and adds one row per commit not yet keyed by
(remote, sha), so a second run or another clone adds nothing. The branch is
the one whose first-parent line holds the commit, the default branch first,
else the one a merge subject names. An unknown label is reported once and
skipped.
Each `--message-block` render appends a row to the score journal the hub's
burndown draws; no gate reads it. Read `journal.md` next to this file
before reading or refilling it.
+25
View File
@@ -0,0 +1,25 @@
# Journal
Each `--message-block` render appends one row to
`${AGENTS_COUNCIL_ROOT:-/tmp/agents-council}/scores.jsonl`: time, origin
remote, top level path, branch, `sha` null, the six values and the block's
digest. The hub's burndown draws it as overlays; no gate reads it. A failed
append prints one stderr line and keeps the exit code; a linked council
root or a link, FIFO or other non-regular file at the journal fails it
without blocking, through `nofollow.py` of `kvb-org-organize`; when that
helper is missing or unusable, the line names it. A new council root gets mode
0700, a new journal 0600.
The journal lives in `/tmp`, so a reboot or another PC starts empty. Refill
it from the blocks in git history, without a model:
```bash
python3 ${CLAUDE_SKILL_DIR}/scripts/backfill.py --repo <dir>... [--since <rev>] [--labels <file>]
```
It reads every local and origin branch, takes the last block of each commit
message, old labels included, and adds one row per commit not yet keyed by
(remote, sha), so a second run or another clone adds nothing. The branch is
the one whose first-parent line holds the commit, the default branch first,
else the one a merge subject names. An unknown label is reported once and
skipped.
+19
View File
@@ -0,0 +1,19 @@
# Tables and message block
Each flag replaces the two lines; values, gate and exit code stay:
- `--table`: one markdown table, `| 🎯 Fix | 💥 Break | 💸 Tokens |
⏱️ Velocity | 🛡️ Security | 🏆 Score | Gate |`.
- `--commit-table <repo>`: that table led by `🌿 Branch | 📊 Diff stat`
from git, 📁 worktree path below, alone in a code block. Every commit
block is this table; after the commit, `--commit <sha>` shows that commit's diff stat
and a `🔖 Commit` column.
- `--message-block`: one value per line, `🎯 Fix: <f> %` through
`🏆 Score: <n>` and `🚦 Gate: <verdict>`. Every commit message carries it
as its own paragraph right before the `Co-Authored-By` line, passed as one
`-m` argument, so the approval prompt and git history show the values.
On a skill change add `--value <n:n|?>`, the quotient of the 💰 line (`?`
while it has no value): a `💰 Value` column after `💸 Tokens`, or line
after `🛡️ Security`. It changes neither score nor gate; alone it is a usage
error.
+1 -1
View File
@@ -48,7 +48,7 @@ LAYOUTS = ((), ("--table",), ("--message-block",))
OLD = re.compile(r"cost|time", re.IGNORECASE)
JOURNAL_NAME = "scores.jsonl"
READERS = {
"skills/kvb-check-score/SKILL.md",
"skills/kvb-check-score/journal.md",
"skills/kvb-check-score/scripts/journal.py",
"orchestrator/kvb_orchestrator/scores.py",
}