@erclx/aitk 0.65.0 → 0.66.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/docs/agents/markdown-audit.md

@@ -55,9 +55,28 @@ Every weight and depth measure counts the text a reader is shown. A link reduces
 
 A code span is walked around rather than through, so a path quoting link or angle-bracket syntax keeps the width the page gives it. Masking inside one takes back the decision to count it, and the placeholders this toolkit writes are where that shows.
 
-The paragraph check is new and measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: measured across 3374 paragraphs, 486 sit inside four sentences and past 400 characters, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
+The paragraph check measures both halves of one rule. `markdown.md` caps a paragraph at four sentences, and a sentence cap on its own is satisfied by writing fewer and longer ones: 88 paragraphs in this corpus sit inside four sentences and past the weight checkpoint, and the heaviest of those runs 1121 characters. The standard therefore states a weight beside the sentence cap, and the verb reads it as its own checkpoint.
 
-The paragraph weight and the bullet weight are the same number today because the two shapes measure one population, sharing a median near 170 characters with no gap behind either candidate. They are separate checkpoints in the standard and separate patterns in the parser, so retuning one leaves the other where it is.
+The paragraph weight sits at 600 and the bullet weight at 400. The two shapes measure one population, sharing a median near 170 characters with no gap behind either candidate, so the paragraph number was borrowed from the bullet rule when both checks shipped. They are separate checkpoints in the standard and separate patterns in the parser, and the sample below moved one and left the other untouched.
+
+#### The sample behind the paragraph number
+
+The checkpoint shipped at 400 as a borrowed number and was decided against a read of the prose it reports. Thirty-six findings were sampled, six from each of six weight bands, drawn at even spacing through each band ordered by path and line, and each was classed as prose a reader wants split or prose the checkpoint should not have reported.
+
+| Band      | Wants the split | Reads as written |
+| --------- | --------------- | ---------------- |
+| 400 - 425 | 1               | 5                |
+| 425 - 450 | 2               | 4                |
+| 450 - 500 | 2               | 4                |
+| 500 - 600 | 2               | 4                |
+| 600 - 750 | 6               | 0                |
+| Past 750  | 6               | 0                |
+
+Precision is what moved the number rather than the finding count. Below 600 the checkpoint was right about seven of twenty-four sampled paragraphs, and past 600 it was right about all twelve. A checkpoint is a prompt to look, and a prompt wrong three times in four teaches a reader to stop looking. The distribution offers no seam to place the number against, with a median of 487 and a seventy-fifth percentile of 563, so the read is the whole of the evidence.
+
+Nothing inside the 500 to 600 band separated the two classes by length, which is the reason the number did not land there. The two paragraphs wanting a split ran 543 and 590 characters against four reading well at 515, 532, 555, and 569.
+
+The sample is thirty-six paragraphs against a reported population in the hundreds, and one reader classed all of them. Treat a band's rate as the order of magnitude it is rather than as a measured precision, and re-sample before moving the number again.
 
 A bullet, a heading, a table row, a blockquote, a blank line, and a fence each end a paragraph, so a heavy bullet is reported by the bullet check alone and never counted twice.
 
@@ -67,9 +86,13 @@ Exit codes are `0` for a completed run and `1` for a refusal. Every finding repo
 
 A banned character is a fact rather than a judgment, which is the test that would ordinarily make it gate. What holds it back is that gating on day one against a corpus never checked mechanically fails loudly on work nobody has had a chance to fix. The order is to land the verb reporting, measure the corpus once, fix what it finds, and turn the gate on as its own change. Bullet, paragraph, and depth weight are judgments and stay advisory under any later gate.
 
-Measured across 444 files once the weight measures moved to visible text: 8 word hits, no character or spelling hits, 119 heavy bullets, 615 heavy paragraphs, and 40 files carrying a run past the depth checkpoint. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+Measured across 444 files with the paragraph checkpoint at 600: 8 word hits, no character or spelling hits, 119 heavy bullets, 221 heavy paragraphs across 86 files, and 41 files carrying a run past the depth checkpoint. Of the paragraphs, 88 fire on weight alone. This is the baseline the corpus sweep tracks its work against. The ban count is what a gate would have to hold at zero, and it is the only one of the five a gate should ever read.
+
+A count written into prose goes stale against the corpus it describes, and nothing compares the two. The paragraph figure recorded when the masking fix shipped was already wrong by twelve one release later, which is why the standard states the rule and this page carries the numbers.
+
+A standard sits inside the corpus this verb measures, so rewriting a rule can breach the rule beside it. A rewrite of the paragraph weight bullet landed at 539 characters against the bullet checkpoint stated two lines below it, in the authoring copy and the consumed one alike. Neither the drift stage nor the test suite reads that, so run the verb over a standard after editing one.
 
-Masking took 7 of the 493 weight-only paragraphs and 4 of the 44 files under their checkpoints, and no bullet at all. The first corpus triage put those at 31 paragraphs and 2 bullets, and neither reproduces: a code span is walked around, so a backticked path holding an angle-bracket placeholder keeps the width the page gives it, and both bullets the triage counted were that shape.
+Masking took 7 of the weight-only paragraphs the checkpoint reported at 400 and 4 of the 44 files under their checkpoints, and no bullet at all. The first corpus triage put those at 31 paragraphs and 2 bullets, and neither reproduces: a code span is walked around, so a backticked path holding an angle-bracket placeholder keeps the width the page gives it, and both bullets the triage counted were that shape.
 
 ## What it does not cover
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/check-seed-independence.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
+
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
+
+TOOLKIT_TOKEN="aitk"
+TOOLING_ROOT="$PROJECT_ROOT/tooling"
+
+# `find` writes to stderr and returns non-zero for a missing root, inside a
+# process substitution whose status nothing reads. Without this the walk covers
+# nothing and the check reports the seeds independent having never read one.
+if [ ! -d "$TOOLING_ROOT" ]; then
+  echo "No tooling root at ${TOOLING_ROOT#"$PROJECT_ROOT/"}, seed independence unverifiable." >&2
+  exit 1
+fi
+
+# An empty discovery is a real state rather than a broken walk, and the Seed
+# standards stage already reports it as a skip. Failing here would have the two
+# stages disagree about what the same condition means.
+seed_roots=$(collect_seed_roots)
+if [ -z "$seed_roots" ]; then
+  echo "No seed root carries .claude/, nothing to check." >&2
+  exit 0
+fi
+
+# Markdown alone. The seed tree also ships hooks that call the toolkit CLI on
+# purpose, each reporting a named stale-index warning when the binary is absent,
+# and scoping by extension leaves them outside this walk without an exemption
+# list that would have to be maintained against them.
+cited=""
+measured=0
+while IFS= read -r seed_root; do
+  while IFS= read -r file; do
+    measured=$((measured + 1))
+    while IFS= read -r hit; do
+      cited="$cited  ${file#"$PROJECT_ROOT/"}:$hit"$'\n'
+    done < <(grep -n "$TOOLKIT_TOKEN" "$file" || true)
+  done < <(find "$PROJECT_ROOT/$seed_root" -type f -name '*.md')
+done <<<"$seed_roots"
+
+# Roots resolved and no markdown under any of them is a walk that covered
+# nothing, which is the verdict-without-a-measurement the guards above refuse for
+# a missing tree. Reporting a pass here would say the seeds cite no CLI on the
+# strength of having read no prose.
+if [ "$measured" -eq 0 ]; then
+  echo "Seed roots resolved but carry no markdown, seed independence unverifiable." >&2
+  exit 1
+fi
+
+if [ -n "$cited" ]; then
+  echo "Seed prose cites the toolkit CLI:" >&2
+  printf '%s' "$cited" >&2
+  echo "A scaffolded project may not have $TOOLKIT_TOKEN installed. State the capability the line needs rather than the binary that supplies it." >&2
+  exit 1
+fi

package/scripts/core/verify.sh

@@ -7,6 +7,7 @@ PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
 source "$PROJECT_ROOT/scripts/lib/ui.sh"
 source "$PROJECT_ROOT/scripts/lib/worktree.sh"
+source "$PROJECT_ROOT/scripts/lib/tooling.sh"
 
 NESTED="${VERIFY_NESTED:-false}"
 WRITE="${VERIFY_WRITE:-true}"
@@ -127,16 +128,6 @@ assert_hero_pair() {
   [ "$html_commit" = "$png_commit" ]
 }
 
-# Whatever stacks the repo currently carries, so a new one is covered without an
-# edit here. A seed root holding no `.claude/` seeds nothing a standard governs.
-collect_seed_roots() {
-  local dir
-  for dir in "$PROJECT_ROOT"/tooling/*/seeds; do
-    [ -d "$dir/.claude" ] || continue
-    printf '%s\n' "${dir#"$PROJECT_ROOT"/}"
-  done
-}
-
 # Entries the audit actually measured, summed across the folders it resolved.
 # `--json` carries one `"entries":<n>` per folder object, and the top-level key
 # of that name holds an array, so the numeric match reaches folders alone.
@@ -214,6 +205,15 @@ main() {
   run_check "bash $PROJECT_ROOT/scripts/core/check-plugin-boundary.sh" "Plugin ships toolkit-internal content."
   log_info "Plugin boundary clean"
 
+  # Seed prose is installed into every scaffolded project and read there as
+  # instruction about that project, so a line naming this repository's CLI hands
+  # a target a verb it may not be able to run. This gates for the reason the
+  # Seed standards stage below gates: a defect authored once propagates into
+  # every project scaffolded after it.
+  log_step "Seed independence"
+  run_check "bash $PROJECT_ROOT/scripts/core/check-seed-independence.sh" "Seed prose cites the toolkit CLI."
+  log_info "Seed prose cites no toolkit CLI"
+
   # A stack entry naming a rule folder takes every rule in it, which is what
   # stops a new rule from needing a second edit to reach a target. The failure
   # it leaves open is a rule authored into a folder no stack names, which

package/scripts/lib/tooling.sh

@@ -22,3 +22,14 @@ list_tooling_stacks() {
     echo "$name"
   done < <(find "$tooling_dir" -mindepth 1 -maxdepth 1 -type d | sort)
 }
+
+# Seed roots that carry a `.claude/`, emitted relative to `PROJECT_ROOT`. Every
+# stage measuring seed content discovers through this rather than naming a stack,
+# so a stack seeding `.claude/` later arrives covered with no edit to any caller.
+collect_seed_roots() {
+  local dir
+  for dir in "$PROJECT_ROOT"/tooling/*/seeds; do
+    [ -d "$dir/.claude" ] || continue
+    printf '%s\n' "${dir#"$PROJECT_ROOT"/}"
+  done
+}

package/src/commands/markdown.ts

@@ -292,7 +292,7 @@ function reportParagraphs(
     `Prose paragraphs report past ${checkpoints.sentences} sentences or past ${checkpoints.paragraph} characters.`,
   )
   logInfo(
-    'The standard states both. Weight matches the bullet checkpoint today and moves independently of it.',
+    'The standard states both, and weight moves independently of the bullet checkpoint.',
   )
   logInfo(
     'Bullets, headings, tables, quotes, and fenced blocks each end a paragraph, so a bullet is measured once.',

package/src/markdown/structure.ts

@@ -45,7 +45,7 @@ export const DEFAULT_CHECKPOINTS = {
   run: 40,
   peerBullet: 130,
   bullet: 400,
-  paragraph: 400,
+  paragraph: 600,
   sentences: 4,
   renderWidth: 80,
 } as const

package/standards/markdown.md

@@ -34,7 +34,7 @@ Does not govern:
 
 - Use prose by default. Reserve bullets for discrete, unrelated items.
 - Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
-- Past roughly 400 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. The sentence cap alone is satisfied by writing fewer and longer sentences, and measured across this corpus 344 paragraphs sit inside four sentences and past this number, so a count on its own passes every one of them.
+- Past roughly 600 characters in one paragraph, folding in the lines that wrap it, split at the next logical boundary as well. A paragraph written as two long sentences satisfies the sentence cap above and still asks the reader to hold too much at once. This number sits above the bullet checkpoint because a paragraph is read straight through and a bullet is scanned.
 - Keep bullets tight. Past roughly 400 characters in one top-level bullet, counting the lines that continue it and excluding any bullet nested under it, the overflow belongs in prose. The number is a checkpoint rather than a cap, and a bullet reading well past it means the number is wrong rather than the rule.
 - Collapse a stack of bullets narrating one subsystem into a single `###` subsection carrying one narrative. Splitting a heavy bullet into three light ones satisfies the checkpoint above and leaves the reader no better off, and subdividing a block does not lighten the bullets inside it, so the two rules answer different defects.
 - Use dashes (`-`) not asterisks (`*`) for bulleted lists

package/tooling/claude/seeds/CLAUDE.md

@@ -74,7 +74,7 @@
 - Write all memory files to `.claude/memory/`, not `~/.claude/projects/`
 - A fact about a domain goes to that domain's `.claude/context/` entry, not to memory. `claude-memory-capture` routes it there and `claude-docs` folds it in. Memory keeps only what no context entry owns.
 - Never delete a memory entry. Retire one by moving it to `.claude/.tmp/memory-archive/`. A bulk retire runs through the shell, where no file edit fires a path-scoped rule, and the folder is gitignored with nothing to recover from.
-- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Run `aitk records validate memory` to check the pen against it.
+- Follow `.claude/standards/memory.md` for the filename and type prefix, the frontmatter, the body shape each type carries, and the lifecycle. Check every entry in the pen against that standard and fix what breaks it, since nothing keeps the folder conforming on its own.
 
 ## Scratch
 
@@ -87,4 +87,4 @@
 - From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
 - From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
 - `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.
-- Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through an `aitk` verb, which resolves the main root in-process, because the shell route for that case is the stream editor this file bans.
+- Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through a command that resolves the main root in-process, because the shell route for that case is the stream editor this file bans.