@erclx/aitk 0.30.1 → 0.32.0

package/README.md

@@ -55,7 +55,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 - [Design system](.claude/context/design.md): `DESIGN.md` token shape, extract skill and its two paths, render command
 - [Slides](.claude/context/slides.md): `SLIDES.md` source, layout catalog, render command, draft skill
 - [Transcripts](.claude/context/transcripts.md): fetch a YouTube transcript with metadata frontmatter via `aitk transcripts`
-- [Sandbox](.claude/context/sandbox.md): scenario-based scaffolds for verifying each domain flow
+- [Sandbox](.claude/context/sandbox/index.md): scenario-based scaffolds for verifying each domain flow
 
 ## Documentation
 

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

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

package/claude/skills/migration-context/REQUIREMENT.md

@@ -0,0 +1,35 @@
+---
+name: migration-context
+description: Scope boundary for the docs audience split and its ordering against the other two migrations
+---
+
+# Migration context requirement
+
+## Gap
+
+Without this skill, a session judges a `docs/` file agent-facing, moves it, and rewrites the inbound links in the same pass, so a classification the user rejects is no longer one command to undo.
+
+Three more failures share a cause. The skill reads a folder two other surfaces also write, and a proposal blind to them destroys work. A seed-derived `development.md` moved out of `docs/` comes back on the next seed sync. A move onto an existing `.claude/context/` filename overwrites the entry sitting there. A proposal drafted while `migration-claude-md` is proposing entries into the same folder cannot see those targets, and running the two in the wrong order turns a legitimate move into a skipped conflict.
+
+## Must
+
+- Classify by audience signal in the file rather than by its name or its folder position
+- Propose and stop. The `git mv` commands and the link fixes stay the user's to run.
+- Report every inbound reference to a moved path as a TODO line, leaving the reference itself untouched
+- Defer a seed-derived file to the seed sync path rather than proposing a move for it
+- Skip a move whose destination already exists and report it as a conflict
+
+## Must not
+
+- Sort a file carrying both audiences into either bucket. Flag it for a manual split, since a whole-file move and a silent split are both wrong.
+- Descend into `docs/` subfolders. List them for manual review and leave them alone.
+
+## Guards
+
+- A missing `docs/` directory, or one holding no top-level markdown, stops before any classification runs
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections, which `migration-claude-md` proposes into this same `.claude/context/` folder. Run this skill first when both apply, so that skill's append-or-create check reads a folder the moves have already populated.
+- Relocating root `standards/` and `snippets/`: `migration-standards`
+- Regenerating `.claude/context/index.md`, which `aitk indexes regen` does once the user has applied the moves

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -0,0 +1,34 @@
+---
+name: setup-gov
+description: Scope boundary for governance rule install and the authoring it refuses to do in a target
+---
+
+# Setup gov requirement
+
+## Gap
+
+Without this skill, a session picks a stack name from memory and installs rules written for a framework the project does not use, passes an extra the catalog does not carry so the install warns on a file it cannot resolve, and adds a rule the picked stack already pulls in.
+
+The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
+
+## Must
+
+- Read the catalog at run time and resolve both the stack and every extra against it
+- Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
+- Dedupe extras against the rules the picked stack already resolves
+- Run the install non-interactively, since the CLI picker blocks where no terminal is attached
+
+## Must not
+
+- Author a rule inside the target project. Rules are authored in the toolkit and reach a project by install or sync.
+- Install a stack or extra whose name did not come from the catalog read
+
+## Guards
+
+- An unmatched technology stops and presents the options rather than resolving to a nearby rule. Authoring the missing rule in the toolkit, installing the matching layers without the technology-specific one, and aborting are the three, and this skill picks none of them.
+
+## Out of scope
+
+- The rest of the onboarding chain. This skill installs governance and nothing else, and `setup-init` is the one-shot path that installs governance beside tooling, standards, snippets, and the seeds.
+- Scaffolding the rule file an unmatched technology needs. `create-rule` writes one into a target project, and a rule the toolkit should ship is authored under `governance/rules/` against `.claude/standards/rule.md`.
+- Updating rules a project already has, which `aitk gov sync` owns

package/claude/skills/setup-init/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: setup-init
+description: Scope boundary for the one-shot onboarding chain and the setup steps it leaves to a caller
+---
+
+# Setup init requirement
+
+## Gap
+
+Without this skill, a session installs a stack whose name it recalled rather than read, hand-writes configs the tooling sync already ships as golden files, and re-runs the chain over a project that owns its configs already.
+
+Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
+
+## Must
+
+- Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
+- Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
+- Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
+- State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+
+## Must not
+
+- Generate a config that tooling sync ships as a golden file. Generating from prose duplicates the installed file and the two drift.
+- Author a rule, stack, or snippet inside the target project when detection finds no match. Authoring happens in the toolkit and reaches a project by install or sync.
+- Grow an existing-project branch, a mode switch, or a clobber guard. The chain runs once against a fresh scaffold and the per-domain paths cover everything after that.
+
+## Guards
+
+- An unmatched technology stops for a decision. Surface the gap and either defer to rule authoring or proceed on the matched layer with the gap named in the report, rather than resolving to the nearest rule.
+
+## Out of scope
+
+- Installing governance rules alone: `setup-gov`. This skill installs governance beside tooling, standards, snippets, and the seeds.
+- Bootstrapping the `index.md` system: `setup-indexes`. Neither `aitk init` nor this chain performs it.
+- Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
+- Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
+- Re-installing into a project that already has the files, which the per-domain `aitk <domain> install` and `aitk sync` commands own

package/docs/agents.md

@@ -391,11 +391,13 @@ 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.
 
 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.
 

package/docs/target-projects.md

@@ -127,7 +127,7 @@ Use a targeted entry point when only one surface moved upstream. Use the catch-a
 
 ## Verify a sync
 
-Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox.md) for the scenario catalog and routing patterns.
+Before running a sync against a real project, run the relevant sandbox scenario. The sandbox provisions a representative project state and routes `SANDBOX_SCENARIO=sync` through the domain flow. See [sandbox](../.claude/context/sandbox/index.md) for the scenario catalog and routing patterns.
 
 ## Scenarios
 
@@ -182,4 +182,4 @@ Sync also refuses a target whose working tree is dirty, so commit or stash befor
 - [agents](agents.md): CLI flags, exit codes, and JSON output shapes
 - [AI workflow](ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [tooling](../.claude/context/tooling.md), [governance](../.claude/context/governance.md), [claude plugin](../.claude/context/claude-plugin/index.md), [indexes](../.claude/context/indexes.md), [snippets](../.claude/context/snippets.md), [standards](../.claude/context/standards.md): per-domain mechanics
-- [sandbox](../.claude/context/sandbox.md): scenario catalog for verifying domain flows
+- [sandbox](../.claude/context/sandbox/index.md): scenario catalog for verifying domain flows

package/package.json

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

package/src/commands/context.ts

@@ -4,6 +4,8 @@ import {
   type EntryReport,
   LENGTH_CHECKPOINT,
   measureFolders,
+  PEER_BULLET_CHECKPOINT,
+  RENDER_WIDTH,
   RUN_CHECKPOINT,
 } from '@/context/audit'
 import { auditCitations, type CitationReport } from '@/context/citations'
@@ -160,6 +162,8 @@ async function runAudit(
           lines: LENGTH_CHECKPOINT,
           run: RUN_CHECKPOINT,
           runCountsBlankLines: true,
+          renderWidth: RENDER_WIDTH,
+          peerBullet: PEER_BULLET_CHECKPOINT,
         },
       })}\n`,
     )
@@ -241,6 +245,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 +263,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 +301,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'),
   )

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
@@ -56,7 +77,20 @@ 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
@@ -90,24 +124,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 +170,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 +191,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 = []
   }
@@ -260,7 +326,10 @@ export function measureEntry(rel: string, source: string): EntryReport {
 
   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),

package/src/sandbox/census.ts

@@ -69,7 +69,7 @@ export function listSkills(root: string): string[] {
 /**
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
- * `<category>-<command>` is the rule `.claude/context/sandbox.md` states, and it
+ * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
  * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two

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.