@erclx/aitk 0.31.0 → 0.33.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.31.0",
+  "version": "0.33.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/bash-script/REQUIREMENT.md

@@ -0,0 +1,36 @@
+---
+name: bash-script
+description: Scope boundary for the interactive script house style and the stream discipline underneath it
+---
+
+# Bash script requirement
+
+## Gap
+
+Without this skill, a session asked for a human-facing shell tool writes one whose frame decoration, log lines, and prompts all land on stdout, so the script cannot be piped and any data it emits arrives mixed with its own presentation.
+
+Three more failures share a cause, which is that an interactive script is written as though a person is always watching. A prompt blocks forever when stdin is not a terminal, which is the shape every CI job and every agent run has. A cancellation path prints both a cancel line and an error, or an exit trap prints a closing frame the success path already printed, so the same run reports twice. And each generated script picks its own icons, casing, and frame characters, so a folder of them reads as several unrelated tools.
+
+The visual conventions this skill fixes are otherwise arbitrary. Their value is that they are the same across every script, which is a property no individual script can establish for itself.
+
+## Must
+
+- Keep every frame, log line, and prompt on stderr, and reserve stdout for data. `--help` is the one exception, since its consumer is a person rather than a pipe.
+- Guard every prompt on an attached terminal and refuse inside the frame rather than blocking on a read that will never return
+- Give the timeline one owner per exit path, so success, cancellation, and error each close it exactly once
+- Copy the shared templates rather than restating them, keeping only the colors and functions the script uses
+
+## Must not
+
+- Assert a convention the generated script cannot be checked against by reading it. A rule that cannot be verified from the output is style with no gate behind it.
+- Carry a second copy of the timeline, logging, or prompt implementations. The bundled reference is the single copy, and a body that restates it drifts from it.
+
+## Guards
+
+- A request for a script with no human at the terminal stops and routes to `cli-script` rather than generating a timeline nothing will render
+
+## Out of scope
+
+- Non-interactive automation, CI, and agent-run scripts: `cli-script`, which keeps the error handling and the stdout contract and drops the timeline, the icons, and the prompts
+- GitHub Actions workflow files: `ci-workflow`
+- What the generated script does. This skill fixes the shape of the output and the stream it goes to, and the commands belong to the request.

package/claude/skills/ci-workflow/REQUIREMENT.md

@@ -0,0 +1,35 @@
+---
+name: ci-workflow
+description: Scope boundary for pipeline structure against job contents, and the reproducibility rules under it
+---
+
+# CI workflow requirement
+
+## Gap
+
+Without this skill, a session writes a pipeline whose jobs run in sequence because `needs` was used to express the order a person reads them in rather than a data dependency. The pipeline then costs the sum of its jobs where it could have cost the longest one, and the waste compounds on every push.
+
+The rest are reproducibility failures that surface as flakes. An action pinned to a moving ref changes under the project, so a run that passed yesterday fails today with no commit behind it and the diff explains nothing. A cache keyed on a static string serves a stale browser or toolchain after a version bump, and the failure reads as a broken test rather than a stale cache. Artifacts upload on every run and never expire, so storage grows with the commit count while the ones worth reading are the failures. And a workflow with no manual trigger can only be reproduced by pushing a commit, which is the wrong instrument for a run that failed for an environmental reason.
+
+## Must
+
+- Gate a job only on a data dependency or on a cost that justifies the wait, and leave every other job parallel
+- Pin every action to a tag that cannot cross a major version
+- Key a cache on the version string of the thing it caches
+- Give every workflow a manual trigger beside its primary one
+- Bound artifact upload to failures and set an expiry on it
+
+## Must not
+
+- Own what runs inside a job. The build, test, and deploy commands come from the project, and a workflow asserting its own is a second copy of the project's scripts.
+- Enumerate the job set as a fixed list. Projects add and remove jobs, and what has to survive that is the parallel and gated structure rather than the roster.
+
+## Guards
+
+- A request for a deploy, publish, or release step stops at the gate. The job's contents carry credentials and an environment this skill cannot see, so it emits the `needs` wiring and names what the caller has to fill in rather than guessing a deploy command.
+
+## Out of scope
+
+- The shell scripts a job invokes: `cli-script`
+- Secrets, environments, and deploy targets, which live in the repository settings rather than in the workflow this skill writes
+- CI systems other than GitHub Actions. The structure rules generalize and the file format does not, so a different system is a different skill rather than a flag on this one.

package/claude/skills/claude-seed-sync/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: claude-seed-sync
+description: Scope boundary for section-granular seed reconciliation against the bulk install and sync commands
+---
+
+# Claude seed sync requirement
+
+## Gap
+
+Without this skill, a project that edited an installed seed or standard has two ways to take an upstream change and both lose something. `aitk standards install` overwrites every file, so the edits are gone with no record of what they were. `aitk standards sync` updates only files it already finds and adds none, so a standard written after the project installed never arrives at all. Neither can deliver one upstream section into a file the project has customized, which is the case a grown project is always in.
+
+A whole-file diff does not close it either. It cannot separate a section the user rewrote on purpose from a section the toolkit moved on without them, so the choice reaches the user as accept everything or lose everything, and the safe answer is always to skip.
+
+Two failures belong to the audit rather than to the diff. A decision taken in chat dies with the session, so an audit half applied cannot be resumed and the second run starts over. And a file the toolkit generates rather than ships, such as an index rebuilt from sibling frontmatter, is absent from every source catalog by design, so a naive comparison reports it as a local addition and invites the user to reconcile something nothing owns.
+
+## Must
+
+- Read seed and standard content from the CLI rather than holding a copy, so the audit and the install cannot disagree
+- Diff per section, treating the preamble as a section of its own
+- Separate a customized section from a stale one, and default the customized one to no action
+- Persist the proposal and every decision to a review file that stays the source of truth across re-pings
+- Apply one section at a time, never by rewriting a file
+
+## Must not
+
+- Propose removing a section present only in the target. Those are the customizations the skill exists to preserve.
+- Write a target file before a decision is recorded against the item
+- Read an empty decision slot as consent
+
+## Guards
+
+- No `aitk` on PATH, or no `.claude/` directory at the project root, stops before any read
+
+## Out of scope
+
+- Bulk install and sync of a whole domain, which `aitk <domain> install` and `aitk <domain> sync` own and `toolkit-cli` documents. Reach for this skill when the target holds edits worth keeping, and for those commands when it does not.
+- Golden configs, which overwrite by design and carry no section structure to diff
+- Governance rules: `aitk gov sync`
+- First-time scaffold of a project that has installed nothing yet: `setup-init`
+- Public `README.md` and `docs/` prose: `docs-sync`

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: docs-sync
+description: Scope boundary for consumer-facing prose against the agent-facing docs the ship chain syncs beside it
+---
+
+# Docs sync requirement
+
+## Gap
+
+Without this skill, a rename or a dropped flag ships with the README still describing the old surface. Nothing fails, because no test reads prose, so the doc stays wrong until a person hits it.
+
+Three failures belong to the sync itself rather than to the drift. A session that syncs by rewriting whole files churns sections the change never reached, which costs the reviewer the ability to tell the sync from the feature. A doc edited earlier in the same session reads as current while a later change leaves one of its sections stale, so file-level classification passes where section-level would not. And a hardcoded doc list never checks the file someone added after the list was written.
+
+The quiet one is the baseline. A diff resolved against a bare local ref equals HEAD on `main` and on a branch before its first commit, so every committed change drops out of the set. The skill then reports nothing to sync, which reads as a clean result rather than as an admission that it could not see the work.
+
+## Must
+
+- Resolve one merge base, prefer the remote ref over the local one, and reuse it everywhere the skill reads the diff
+- Say so in the output when the baseline degrades, rather than reporting a clean pass off a set it could not build
+- Discover the doc set by glob at run time
+- Classify and rewrite at section level, so a partly stale file is partly rewritten
+- Write immediately after the preview, since the tool permission dialog is the confirmation gate
+
+## Must not
+
+- Touch a section the change does not reach
+- Rewrite a doc to match the diff when the doc records an intent the diff departed from. That is a finding rather than a sync.
+
+## Guards
+
+- No committed change and no working-tree change stops the skill before it reads any doc
+
+## Out of scope
+
+- `.claude/` planning docs, tasks, plans, and context entries: `claude-docs`, which runs immediately before this skill in the ship chain and resolves the same baseline. The split is by audience, so a file's location decides which skill owns it rather than its subject.
+- `CLAUDE.md` and the installed seed docs: `claude-seed-sync`, which reconciles them per section against the toolkit source
+- Changelog entries, which release tooling generates from commit messages
+- Whether the prose conforms to its standards. `claude-standards-audit` reports violations and fixes none, and this skill writes prose it does not audit.

package/docs/agents.md

@@ -391,11 +391,15 @@ Exit codes are `0` for a clean run, `1` for a refusal, and `2` for an unresolved
 
 ### What each check reports
 
-Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 lines for an entry, roughly 40 for a run of lines no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. The report states the convention on every run.
+Length and depth quote their checkpoints from `.claude/standards/context.md`: roughly 150 rendered lines for an entry, roughly 40 for a run no heading breaks. Depth measures the longest such run rather than everything under one `##`, skips fenced blocks so a markdown example does not read as three headings, and exempts a run whose lines are all list items at one indent averaging under 130 characters. The weight condition is what separates a scannable catalog of one-liners from a stack of paragraph-bullets, which reach the same count and read nothing alike.
+
+Both checks count rendered lines rather than source lines, wrapping each line at 80 columns and summing the heights. Entries here are authored one line per bullet, so a block of fifteen paragraph-bullets occupies fifteen source lines and renders past sixty, which source counting cannot see. Measuring one checkpoint in each unit would put an entry length beside a run length that mean different things. Their exclusions still differ: the file measure counts fenced blocks and frontmatter, while the run measure skips a fence so an example cannot break the run around it. A reference-heavy entry therefore ranks by its examples, which the length legend states on every run. Runs count blank lines, which the standard leaves open, so a hand reader who drops them lands a line or two lower. Both sections state the width on every run, since a number in rendered lines cannot be reproduced without it.
 
 The table check reports a catalog that grows a row per shipped thing, not a table count. A fixed comparison table never reflows, so its size costs nothing. A table qualifies at six or more body rows whose first column mostly carries a path, command, or link, which is what separates a catalog from a comparison without reading the prose.
 
-The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since every check reads the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle.
+The provenance check reports the markers narrating how a domain reached its shape rather than describing what it is: a date, a change number, or a release label. The standard admits a rejected alternative and the reasoning that killed it while refusing the provenance attached to it, so a marker names a line to read rather than a line to delete. Findings group by entry and sort left to right within a line, since what a reader acts on is which file to open. Fenced blocks are excluded, which keeps a pinned version in an install command from reading as a claim the entry makes. Frontmatter is excluded with them, since the content checks read the body alone, and that is what keeps a diagram entry's dated `verified` stamp a record of its last check rather than a marker to settle. Length is the exception, counting the whole file, so a reader applying the 150-rendered-line checkpoint against the body alone lands a few lines under what the tool reports.
+
+This one check covers `.claude/context/` alone, while length, depth, and the table finding reach every audited folder. The rule is stated in `.claude/standards/context.md`, which opens its scope by handing diagrams and wireframes to `diagrams.md` and `wireframes.md`, and the sibling standards do not restate it. A marker reported in a diagram entry would cite a rule that entry's own standard routes elsewhere. The split is between kinds of rule rather than kinds of folder: a threshold on how far a reader travels generalizes across entry types, while a rule about what an entry may say is the jurisdiction a scope statement exists to settle. The scoping key is the folder an entry was audited under, so `--folder` still reaches a folder the default list does not carry, and a domain split into `context/<sub-area>/` is governed as `context`. Every run states the reach, including a run where no audited folder is the governed one. The JSON record carries it as `checkpoints.provenanceFolder` and a per-folder `governsContent`.
 
 Index drift compares an index against its siblings in both directions. An entry the index does not link is invisible to a session choosing what to open, and a linked name resolving to nothing sends one to a path that opens nothing.
 
@@ -411,15 +415,15 @@ What remains is a sentence naming a hypothetical entry to show the shape of a na
 
 Use these to discover what's available instead of hardcoding names.
 
-| Command                          | Returns                                      |
-| -------------------------------- | -------------------------------------------- |
-| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts |
-| `aitk snippets list --json`      | Presets and categories with their slugs      |
-| `aitk standards list --json`     | Standards docs and the paths each governs    |
-| `aitk gov list --json`           | Governance stacks and rule sets              |
-| `aitk claude seeds list --json`  | Seed doc sources with content                |
-| `aitk claude skills list --json` | Plugin skills with their descriptions        |
-| `aitk docs list --json`          | Consumer docs plus per-domain context        |
+| Command                          | Returns                                       |
+| -------------------------------- | --------------------------------------------- |
+| `aitk tooling list --json`       | Stacks, extends chain, dep and script counts  |
+| `aitk snippets list --json`      | Presets and categories with their slugs       |
+| `aitk standards list --json`     | Standards docs and the paths each governs     |
+| `aitk gov list --json`           | Governance stacks and rule sets               |
+| `aitk claude seeds list --json`  | Seed doc sources with content                 |
+| `aitk claude skills list --json` | Plugin skills, descriptions, requirement flag |
+| `aitk docs list --json`          | Consumer docs plus per-domain context         |
 
 Every catalog serializes through `JSON.stringify`, so a name carrying a quote
 emits valid JSON. `aitk tooling list` and `aitk snippets list` previously built
@@ -446,6 +450,12 @@ or unparseable returns an empty description rather than failing the listing, so
 one malformed file cannot hide the rest of the catalog. `--names` emits skill
 names one per line.
 
+Each entry also carries `requirement`, whether the folder holds a sibling
+`REQUIREMENT.md`. Coverage of that file is selective by design, so a `false` is
+not a gap to close and the flag answers which skills carry one without a caller
+listing the directory itself. It says nothing about why, which is a judgment the
+toolkit records against its own corpus rather than in the catalog.
+
 ## Non-interactive examples
 
 ```bash

package/package.json

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

package/src/claude/skills-list.ts

@@ -6,6 +6,7 @@ const FRONTMATTER = /^---\n([\s\S]*?)\n---/
 export interface SkillListing {
   readonly name: string
   readonly description: string
+  readonly requirement: boolean
 }
 
 /**
@@ -15,6 +16,10 @@ export interface SkillListing {
  *
  * The folder name wins over the frontmatter `name` when they disagree, because
  * Claude Code invokes a skill by its directory.
+ *
+ * `requirement` reports whether the folder carries `REQUIREMENT.md`. Coverage is
+ * selective by design, so a false is not a gap to close and this field carries no
+ * reason for one. The toolkit records those separately from the catalog.
  */
 export function listSkills(root: string): SkillListing[] {
   const skillsRoot = join(root, 'claude', 'skills')
@@ -30,6 +35,7 @@ export function listSkills(root: string): SkillListing[] {
   return paths.map((path) => ({
     name: dirname(path),
     description: readDescription(join(skillsRoot, path)),
+    requirement: existsSync(join(skillsRoot, dirname(path), 'REQUIREMENT.md')),
   }))
 }
 

package/src/commands/context.ts

@@ -2,8 +2,12 @@ import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
   type EntryReport,
+  governsContent,
   LENGTH_CHECKPOINT,
   measureFolders,
+  PEER_BULLET_CHECKPOINT,
+  PROVENANCE_FOLDER,
+  RENDER_WIDTH,
   RUN_CHECKPOINT,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -88,8 +92,8 @@ function parseFolders(list: string | undefined): string[] | string {
 
   if (names.length === 0) return 'Empty --folder list. Pass at least one name.'
 
-  // `..` would resolve the audit root above `.claude/`, where `presentNames`
-  // has no folder name to slice out and hands the citation pattern undefined.
+  // `..` would resolve the audited folder above `.claude/`, taking the scan
+  // and the citation pattern outside the tree the audit describes.
   const invalid = names.filter((name) => !FOLDER_NAME.test(name))
   if (invalid.length > 0) {
     return `--folder takes folder names under .claude/, not paths: ${invalid.join(', ')}`
@@ -136,7 +140,7 @@ async function runAudit(
     reportLength(entries)
     reportDepth(entries)
     reportTables(entries)
-    reportProvenance(entries)
+    reportProvenance(entries, folders)
     reportDrift(drift)
     outro()
   }
@@ -148,6 +152,7 @@ async function runAudit(
         folders: folders.map((folder) => ({
           path: folder.rel,
           entries: folder.entries.length,
+          governsContent: governsContent(folder),
         })),
         citations: {
           scanned: citations.scanned,
@@ -160,6 +165,9 @@ async function runAudit(
           lines: LENGTH_CHECKPOINT,
           run: RUN_CHECKPOINT,
           runCountsBlankLines: true,
+          renderWidth: RENDER_WIDTH,
+          peerBullet: PEER_BULLET_CHECKPOINT,
+          provenanceFolder: PROVENANCE_FOLDER,
         },
       })}\n`,
     )
@@ -241,6 +249,12 @@ function reportCitations(report: ScannedCitations): void {
 
 function reportLength(entries: readonly EntryReport[]): void {
   logStep('Length')
+  logInfo(
+    `Entries measure rendered lines at ${RENDER_WIDTH} columns, counting frontmatter and fenced blocks.`,
+  )
+  logInfo(
+    'A reference-heavy entry therefore ranks by its examples, which the depth check excludes.',
+  )
 
   const over = entries
     .filter((entry) => entry.lines > LENGTH_CHECKPOINT)
@@ -253,20 +267,29 @@ function reportLength(entries: readonly EntryReport[]): void {
 
   logWarn(`${over.length} past the ${LENGTH_CHECKPOINT}-line checkpoint`)
   pipeOutput(
-    over.map((entry) => `${entry.rel}  ${entry.lines} lines`).join('\n'),
+    over
+      .map((entry) => `${entry.rel}  ${entry.lines} rendered lines`)
+      .join('\n'),
   )
 }
 
 /**
- * Names the blank-line convention on every run.
+ * Names the render width and the blank-line convention on every run.
  *
  * The standard settles heading level and fenced blocks and stops there, so a
  * hand reader who drops blank lines lands a line or two below this number.
- * Stating it is what keeps the two measurements reconcilable.
+ * Stating both is what keeps the two measurements reconcilable, and the width
+ * matters more than the blank lines because a number counted in rendered lines
+ * cannot be reproduced without it.
  */
 function reportDepth(entries: readonly EntryReport[]): void {
   logStep('Depth')
-  logInfo('Runs count blank lines. Fenced blocks and peer lists are excluded.')
+  logInfo(
+    `Runs measure rendered lines at ${RENDER_WIDTH} columns and count blank lines.`,
+  )
+  logInfo(
+    `Fenced blocks are excluded, and so are peer lists averaging under ${PEER_BULLET_CHECKPOINT} characters a bullet.`,
+  )
 
   const over = entries
     .filter((entry) => entry.longestRun > RUN_CHECKPOINT)
@@ -282,7 +305,7 @@ function reportDepth(entries: readonly EntryReport[]): void {
     over
       .map(
         (entry) =>
-          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} lines unbroken`,
+          `${entry.rel}:${entry.longestRunLine}  ${entry.longestRun} rendered lines unbroken`,
       )
       .join('\n'),
   )
@@ -313,9 +336,28 @@ function reportTables(entries: readonly EntryReport[]): void {
  * time, and a flat list of those buries the entries holding one. What a reader
  * acts on is which file to open, so the count sits beside the name and the
  * lines follow it.
+ *
+ * The reach is stated on every run, including the run where nothing is in
+ * scope. A check that covered three folders and now covers one reads as quietly
+ * missing things unless the report says which folder it measured.
  */
-function reportProvenance(entries: readonly EntryReport[]): void {
+function reportProvenance(
+  entries: readonly EntryReport[],
+  folders: readonly AuditedFolder[],
+): void {
   logStep('Provenance')
+
+  const governed = folders.filter(governsContent)
+  if (governed.length === 0) {
+    logInfo(
+      `Out of scope. The rule is stated in the standard governing .claude/${PROVENANCE_FOLDER}/, and no audited folder is that one.`,
+    )
+    return
+  }
+
+  logInfo(
+    `Covers .claude/${PROVENANCE_FOLDER}/ alone, whose standard carries the rule. The sibling standards do not restate it.`,
+  )
   logInfo('Fenced blocks are excluded. A marker is a judgment, never a defect.')
 
   const carrying = entries

package/src/context/audit.ts

@@ -6,6 +6,27 @@ import type { AuditedFolder } from '@/context/folders'
 export const LENGTH_CHECKPOINT = 150
 export const RUN_CHECKPOINT = 40
 
+/**
+ * Columns a source line wraps at when rendered.
+ *
+ * Nothing in this repository sets a line width and entries are authored one
+ * line per bullet, so the rendered width is the viewer's rather than the file's.
+ * The common terminal and diff width is the reproducible choice, and the report
+ * legend states it so a reader can arrive at the same number by hand.
+ */
+export const RENDER_WIDTH = 80
+
+/**
+ * Characters a bullet averages before its list stops reading as a set of peers.
+ *
+ * The exemption below covers a flat catalog of one-liners and a stack of
+ * paragraphs equally, and only the first is navigable. Measured across this
+ * corpus the two shapes separate with nothing between roughly 100 and 170
+ * characters a bullet, so the midpoint splits the population rather than a
+ * continuum. It is a checkpoint like the two above, not a cap.
+ */
+export const PEER_BULLET_CHECKPOINT = 130
+
 /**
  * A table this size or larger whose first column mostly names artifacts reads
  * as a catalog that grows a row per shipped thing, which is the shape the
@@ -40,6 +61,25 @@ const PROVENANCE: readonly { kind: ProvenanceKind; pattern: RegExp }[] = [
   { kind: 'release', pattern: /\bv\d+\.\d+(?:\.\d+)?\b/g },
 ]
 
+/**
+ * The folder whose standard carries the exclusion above.
+ *
+ * `standards/context.md` opens its scope by handing diagrams and wireframes to
+ * `diagrams.md` and `wireframes.md`, so a marker reported in either would cite
+ * a rule that entry's own standard routes elsewhere. The length, depth, and
+ * table checkpoints are quoted from the same standard and keep reaching every
+ * audited folder, because a threshold on how far a reader travels generalizes
+ * across entry types while a rule about what an entry may say does not.
+ *
+ * Restating the exclusion in the sibling standards was the alternative. It
+ * duplicates one knowledge item across three surfaces, which the root
+ * instruction file forbids, and pointing is not available because the surface
+ * they would point at is the one disclaiming them. Should a diagram entry ever
+ * accumulate narration, the escalation is an attribute standard owning the rule
+ * across document types, not restoring this reach without an owner.
+ */
+export const PROVENANCE_FOLDER = 'context'
+
 export type ProvenanceKind = 'date' | 'change' | 'release'
 
 export interface TableFinding {
@@ -56,11 +96,25 @@ export interface ProvenanceFinding {
 
 export interface EntryReport {
   readonly rel: string
+  /**
+   * Rendered lines across the whole file, counting frontmatter and fenced
+   * blocks. Both this and `longestRun` measure in the same unit, since the two
+   * checkpoints they feed sit in one section of the standard and a reader
+   * compares them.
+   *
+   * The exclusions differ on purpose. `longestRun` skips a fence so an example
+   * cannot break the run around it, and a file measure has no run to protect.
+   * Excluding fences here would change which entries report by one and would
+   * not reach the case that motivates it: the most fenced entry in the corpus
+   * runs 20 percent fenced and sits past the checkpoint either way.
+   */
   readonly lines: number
+  /** Rendered lines at `RENDER_WIDTH`, not source lines. */
   readonly longestRun: number
   /** First line of the longest run, or 0 when the entry has no run at all. */
   readonly longestRunLine: number
   readonly catalogTables: readonly TableFinding[]
+  /** Empty for an entry no standard bans a change narrative in. */
   readonly provenance: readonly ProvenanceFinding[]
 }
 
@@ -90,24 +144,44 @@ function bodyLines(source: string): BodyLine[] {
  *
  * Every non-blank line has to be a list item at one indent. Prose mixed into
  * the run or a nested level inside it ends the exemption, because either one
- * means the block is no longer a flat set a reader can skim.
+ * means the block is no longer a flat set a reader can skim. Bullet count says
+ * nothing on its own, since a catalog of one-liners and a wall of paragraphs
+ * reach the same count and read nothing alike, so the average bullet is what
+ * decides whether the set is still skimmable.
  */
-function isPeerList(run: readonly BodyLine[]): boolean {
+function isScannablePeerList(run: readonly BodyLine[]): boolean {
   const indents = new Set<number>()
+  let items = 0
+  let characters = 0
 
   for (const line of run) {
-    if (line.text.trim() === '') continue
+    const text = line.text.trim()
+    if (text === '') continue
 
     const match = line.text.match(LIST_ITEM)
     if (!match) return false
     indents.add(match[1].length)
+    items++
+    characters += text.length
   }
 
-  return indents.size === 1
+  if (indents.size !== 1) return false
+
+  return characters / items < PEER_BULLET_CHECKPOINT
 }
 
 /**
- * Measures the longest run of lines no heading breaks.
+ * Height a source line occupies once wrapped.
+ *
+ * A blank line renders as the gap it is rather than as nothing, which keeps it
+ * the distance the source measure already counted it as.
+ */
+function renderedHeight(text: string): number {
+  return Math.max(1, Math.ceil(text.length / RENDER_WIDTH))
+}
+
+/**
+ * Measures the longest run of lines no heading breaks, in rendered lines.
  *
  * Fenced blocks are skipped rather than treated as breaks, per the standard:
  * they leave the count without ending the run, so prose either side of an
@@ -116,6 +190,11 @@ function isPeerList(run: readonly BodyLine[]): boolean {
  * between signposts and a blank line is distance like any other. A hand reader
  * measuring without them lands one or two lines lower, which the report legend
  * states.
+ *
+ * Height is what a reader travels, and source lines only stand in for it while
+ * lines stay short. An entry authored one line per bullet puts a paragraph on
+ * each, so a block of fifteen bullets measures as fifteen and renders past
+ * sixty. Wrapping every line at a stated width is what closes that gap.
  */
 function longestRun(lines: readonly BodyLine[]): {
   length: number
@@ -132,9 +211,16 @@ function longestRun(lines: readonly BodyLine[]): {
     // two headings rather than a stretch a reader travels, so it never counts.
     const first = run.find((line) => line.text.trim() !== '')
 
-    if (first && run.length > longest && !isPeerList(run)) {
-      longest = run.length
-      longestLine = first.number
+    if (first && !isScannablePeerList(run)) {
+      const height = run.reduce(
+        (sum, line) => sum + renderedHeight(line.text),
+        0,
+      )
+
+      if (height > longest) {
+        longest = height
+        longestLine = first.number
+      }
     }
     run = []
   }
@@ -254,17 +340,31 @@ function provenance(lines: readonly BodyLine[]): ProvenanceFinding[] {
     .map((each) => each.finding)
 }
 
-export function measureEntry(rel: string, source: string): EntryReport {
+/**
+ * Measures one entry, scanning for provenance only when a standard claims it.
+ *
+ * The caller passes jurisdiction rather than deriving it from `rel`, because a
+ * path prefix hardcodes what `--folder` exists to override and misses a domain
+ * split into `context/<sub-area>/`.
+ */
+export function measureEntry(
+  rel: string,
+  source: string,
+  governsContent = true,
+): EntryReport {
   const lines = bodyLines(source)
   const run = longestRun(lines)
 
   return {
     rel,
-    lines: source.replace(/\n$/, '').split('\n').length,
+    lines: source
+      .replace(/\n$/, '')
+      .split('\n')
+      .reduce((sum, text) => sum + renderedHeight(text), 0),
     longestRun: run.length,
     longestRunLine: run.line,
     catalogTables: catalogTables(lines),
-    provenance: provenance(lines),
+    provenance: governsContent ? provenance(lines) : [],
   }
 }
 
@@ -272,6 +372,9 @@ export function measureEntry(rel: string, source: string): EntryReport {
  * Measures every entry in the audited folders. A generated `index.md` is not
  * among them, since its body is rewritten on every regen and no checkpoint
  * describes a catalog.
+ *
+ * Jurisdiction is applied here rather than at the report, so the JSON record
+ * and the printed run agree on which entries a content rule reached.
  */
 export async function measureFolders(
   root: string,
@@ -282,10 +385,19 @@ export async function measureFolders(
   for (const folder of folders) {
     for (const path of folder.entries) {
       reports.push(
-        measureEntry(relative(root, path), await readFile(path, 'utf8')),
+        measureEntry(
+          relative(root, path),
+          await readFile(path, 'utf8'),
+          governsContent(folder),
+        ),
       )
     }
   }
 
   return reports
 }
+
+/** Reports whether the folder's standard is the one carrying the exclusion. */
+export function governsContent(folder: AuditedFolder): boolean {
+  return folder.name === PROVENANCE_FOLDER
+}

package/src/context/folders.ts

@@ -18,6 +18,13 @@ export const DEFAULT_FOLDERS: readonly string[] = [
 ]
 
 export interface AuditedFolder {
+  /**
+   * The requested folder name this was resolved under, which is what says
+   * which standard governs the entries. A nested split folder carries the name
+   * of the folder it sits beneath rather than its own, so
+   * `.claude/context/claude-plugin` is governed as `context`.
+   */
+  readonly name: string
   /** Repo-relative folder path, used verbatim in every report line. */
   readonly rel: string
   readonly indexPath: string
@@ -35,7 +42,7 @@ export interface AuditedFolder {
  * here for the sole reason that this repository has no wireframes.
  */
 export function presentNames(folders: readonly AuditedFolder[]): string[] {
-  return [...new Set(folders.map((folder) => folder.rel.split('/')[1]))]
+  return [...new Set(folders.map((folder) => folder.name))]
 }
 
 async function readEntries(dir: string): Promise<string[]> {
@@ -80,6 +87,7 @@ export async function resolveFolders(
 
     for (const each of [...new Set(dirs)].sort()) {
       folders.push({
+        name,
         rel: relative(root, each),
         indexPath: `${each}/${INDEX_FILE}`,
         entries: await readEntries(each),

package/standards/context.md

@@ -100,9 +100,10 @@ Only the `development` entry carries this section. It is not a general-purpose h
 ## Length
 
 - Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
-- Past roughly 150 lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
-- Past roughly 40 lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
-- Exempt a block whose lines are all list items at one level. A long list of peers is already navigable, and a subheading dropped into it splits a set that belongs together. Mixing prose with the list, or nesting levels inside it, ends the exemption.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number.
+- Past roughly 40 rendered lines with no heading of any level breaking them, add a subheading at the seam. Measure the longest such run rather than everything under one `##`, and exclude fenced code blocks. The number is a checkpoint like the 150 above, not a cap.
+- Both checkpoints count rendered lines, so wrap each source line at 80 columns and sum the heights. Source lines undercount an entry authored one line per bullet, where a block of fifteen paragraph-bullets occupies fifteen lines and renders past sixty. Counting the two checkpoints in different units would put a file measured one way beside a run measured another.
+- Exempt a block whose lines are all list items at one level averaging under roughly 130 characters. A flat list of short peers is already navigable, and a subheading dropped into it splits a set that belongs together. Bullet count says nothing on its own, since a catalog of one-liners and a stack of paragraphs reach the same count and read nothing alike, so weight is what decides. Mixing prose with the list, or nesting levels inside it, ends the exemption at any weight.
 - Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
 - Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
 - Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.

package/standards/tasks.md

@@ -48,7 +48,33 @@ Readiness is three groups under fixed headings, `## Run now`, `## Up next`, and
 - `## Up next`: a written plan exists, and the task either collides with something running or waits on another task to land. The blocker column names which.
 - `## Needs a plan`: everything else. The task has no plan, or the plan it carries no longer describes the work.
 
-Each group fixes its own columns, which follow from the test above it rather than from preference. `## Run now` carries `Task`, `Touches`, and `Plan`, since neither half of its test is checkable without the last two. `## Up next` carries `Task`, `Touches`, and `Waiting on`, the last naming whether a collision or a dependency holds it. `## Needs a plan` carries `Task` and `Waiting on` alone, because a task with no plan has no bounded file set to state.
+Each group fixes its own columns, which follow from the test above it rather than from preference. Neither half of the `## Run now` test is checkable without the file set and the plan sitting beside the task. The blocker column under `## Up next` names whether a collision or a dependency holds the row. `## Needs a plan` states no file set at all, because a task with no plan has no bounded one to state. A group with no rows keeps its heading and its header row.
+
+```markdown
+---
+title: Priority
+description: One line on what the board covers
+---
+
+# Priority
+
+## Run now
+
+| Task                            | Touches                 | Plan                                 |
+| ------------------------------- | ----------------------- | ------------------------------------ |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <what the task touches> | [<slug>](../plans/feature-<slug>.md) |
+
+## Up next
+
+| Task | Touches | Waiting on |
+| ---- | ------- | ---------- |
+
+## Needs a plan
+
+| Task                            | Waiting on                              |
+| ------------------------------- | --------------------------------------- |
+| [vXX.Y <slug>](vXX.Y-<slug>.md) | <the collision or the task it waits on> |
+```
 
 The tests live here so the board does not carry them. Writing them as a sentence under each heading produces the paragraph the rule above deletes, and a criterion with no home gets restated from memory every time the board is touched.