@erclx/aitk 0.8.0 → 0.10.0

package/src/indexes/walk.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
-import { $ } from 'bun'
+import { listIgnored } from '@/git-ignore'
 
 const INDEX_FILE = 'index.md'
 
@@ -42,34 +42,6 @@ export async function listIndexes(root: string): Promise<string[]> {
   return candidates.filter((path) => !ignored.has(path))
 }
 
-async function listIgnored(
-  root: string,
-  candidates: string[],
-): Promise<Set<string>> {
-  const isRepo = await $`git -C ${root} rev-parse --git-dir`
-    .quiet()
-    .nothrow()
-    .then((result) => result.exitCode === 0)
-
-  if (!isRepo) return new Set()
-
-  const stdin = Buffer.from(`${candidates.join('\n')}\n`)
-
-  const result = await $`git -C ${root} check-ignore --stdin < ${stdin}`
-    .quiet()
-    .nothrow()
-
-  if (result.exitCode > 1) return new Set()
-
-  return new Set(
-    result
-      .text()
-      .split('\n')
-      .filter(Boolean)
-      .map((path) => resolve(root, path)),
-  )
-}
-
 /**
  * Reports whether git ignores `path`.
  *

package/standards/diagrams.md

@@ -1,34 +1,83 @@
 ---
 title: Diagram reference
-description: Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+description: Shape and content rules for .claude/diagrams/<kind>.md files
 ---
 
 # Diagram reference
 
-Applies to Mermaid diagrams in `.claude/DIAGRAMS.md`. Goal: diagrams that render cleanly in narrow-column renderers (VS Code preview, GitHub PR view, Cursor) and read pedagogically without surrounding prose.
+Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`.
+
+A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
+
+## What a working entry looks like
+
+An entry works when a reader who has not opened the repository can answer its question:
+
+- What are the parts, and which ones talk to each other?
+- Which direction does the work flow, and where does it start?
+- What would break if one box were removed?
+
+An entry that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
+- `description` (required): one line on which question the entry settles and which source signal drives it.
+- `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `aitk indexes regen` renders headings from.
+
+All three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+
+## Entry kinds
+
+Five kinds, each with a fixed filename and a fixed `category` value. Write a kind only when its source signal exists, and leave the rest absent rather than padding the folder.
+
+- `system-context.md`, category `System context` (`flowchart TB`): who uses the system, what it talks to, and where its boundary sits. Drawn from `.claude/REQUIREMENTS.md`. This is the entry a reader outside the team opens first, and the only kind that draws the world outside the boundary.
+- `components.md`, category `Components` (`flowchart TB` with `subgraph` boundaries): the layered structure inside the boundary. Drawn from `.claude/ARCHITECTURE.md`.
+- `request-flow.md`, category `Request flow` (`sequenceDiagram`): a request lifecycle, an agent loop, or an interaction between actors.
+- `data-pipeline.md`, category `Data pipeline` (`flowchart TB`): retrieval, ranking, queues, or ETL.
+- `deployment.md`, category `Deployment` (`flowchart TB`): hosts, services, and infrastructure config.
+
+The filenames are fixed rather than free, so a session refreshing one kind finds the file it is meant to overwrite instead of writing a second entry beside it under a name of its own.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+The kinds drift at rates spanning roughly an order of magnitude, which is why they are separate files. A deploy change rewrites one entry and leaves the other four untouched.
+
+A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and repeats the kind's `category` verbatim, which is what the grouping field is for. One entry per kind is the ordinary case, so most catalogs show one entry under each heading.
 
 ## Layout
 
 - Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
 - Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
-- Render a component, context, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
+- Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
 - Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
 - Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
 - Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
 - Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
-- Subgraphs are for grouping unrelated lanes (offline versus online, browser versus server). Do not subgraph a single linear flow.
+- Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
 
 ## Budgets
 
 - Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
 - Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
 - Treat a diagram that cannot be described in one sentence as two diagrams.
+- Keep an entry to one diagram by default. A second fence in the same file needs its own H2 naming what it adds, and a third is a sign the entry covers two kinds.
 - Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement in this repository, so a hard refusal on them will be wrong sometimes and unarguable when it is.
 
 ## Accessibility
 
 - Give every diagram `accTitle` and `accDescr`. `accTitle` names what the diagram answers. `accDescr` states the structure in one sentence for a reader who cannot see the render.
 
+## Explanation
+
+- One to three short paragraphs below each diagram. Plain English and pedagogical.
+- Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
+- Reference one or two specific code paths the reader can open. Do not enumerate every file.
+- Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
+- The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
+
+This section states the voice for the surface, which is what claims the yield `standards/prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force, and the standards-audit hook enforces them on every write.
+
 ## Verification
 
 - Judge a diagram from its rendered image, not from its source. Direction, sibling rows, and edge bundles are visible only in the output.
@@ -36,20 +85,21 @@ Applies to Mermaid diagrams in `.claude/DIAGRAMS.md`. Goal: diagrams that render
 - Apply four tests as a reviewer, the same ones the author applied: direction held, no sibling row reading as a chain, no crossing edge bundle, taller than wide outside a sequence diagram.
 - State which verification was skipped when no renderer is available. A diagram written without a render is still shippable, and one reported as verified without a render is not.
 
-## Narrative
+## What moves to .claude/context/
 
-- Build a narrative arc across the file, not a parallel list of unrelated views. Start with the whole system in five or six boxes. Drill into one phase per section.
-- Order sections chronologically when possible: framing, then setup, then a query travels through, then measurement.
-- One H2 per diagram. The H2 names what the diagram answers, not what it shows ("How the corpus gets populated", not "Corpus ingestion").
+Implementation detail that answers how a component is built belongs in a `.claude/context/` entry, not a diagram:
 
-## Explanation
+- Function names, call signatures, and lifecycle ordering
+- Library versions, config keys, and environment variable names
+- Retry counts, timeouts, and batch sizes
+- Workarounds and rejected approaches that need more than one sentence
 
-- One to three short paragraphs below each diagram. Plain English, pedagogical, no marketing copy.
-- Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
-- Reference one or two specific code paths the reader can open. Do not enumerate every file.
-- Do not duplicate prose between sections. Each paragraph earns its line.
+Reference the context entry by path when a reader needs the mechanism. The diagram stays answerable on its own for structure and flow.
 
 ## Maintenance
 
-- When the system changes (new layer, new provider, new deploy posture), audit `.claude/DIAGRAMS.md` in the same PR. A diagram showing a defunct host or library is worse than no diagram.
-- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraph below is still prose. Follow `standards/prose.md`.
+- When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
+- A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
+- `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
+- The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/index.md

@@ -10,9 +10,9 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Architecture reference](architecture.md): Shape and content rules for .claude/ARCHITECTURE.md
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
-- [Diagram reference](diagrams.md): Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+- [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
 - [Prose reference](prose.md): Voice, structure, formatting, and language rules for reference markdown
-- [Readme reference](readme.md): Readme structure and content conventions
+- [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
 - [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules

package/standards/prose.md

@@ -5,7 +5,7 @@ description: Voice, structure, formatting, and language rules for reference mark
 
 # Prose reference
 
-Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages.
+Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. Punctuation, formatting, and language rules below stay in force on every surface, including the surfaces no automated check reaches, which is what the scan below is for.
 
 ## Voice
 
@@ -74,6 +74,19 @@ Applies to markdown reference docs, READMEs, and inline documentation in repos.
 - Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
 - Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
 
+## Banned-character scan
+
+Wherever text leaves through a channel no automated check covers, the author is the only gate and runs this scan. Text sent to another service, written to a path the project's checks exclude, and text inside a fenced block are the usual cases. The surface that publishes the text is what knows which gap applies, so it names its own rather than reading one here.
+
+Scan the drafted text and rewrite each occurrence:
+
+- `—` (em dash): split into two sentences, or use a comma
+- `;` (semicolon): split into two sentences
+
+Restructure the sentence rather than substituting the character. A semicolon swapped for a period leaves both clauses in the order the semicolon chose, which is the shape the ban exists to remove.
+
+Run the scan as an explicit step against the finished text. Having read this file before drafting does not cover it, because the check has to happen after the text exists.
+
 ## Frontmatter descriptions
 
 When frontmatter carries a short `title` or `description` used for catalog display:

package/standards/readme.md

@@ -1,10 +1,24 @@
 ---
 title: Readme reference
-description: Readme structure and content conventions
+description: Readme voice, structure, and content conventions
 ---
 
 # Readme reference
 
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so `prose.md` yields to it there. The yield covers voice alone. The punctuation bans, spelling rules, banned words, and formatting rules in `prose.md` stay in force, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no buzzwords.
+
+The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
+
+## Voice
+
+Scoped to the README at a repository root. A nested README documenting a folder, a harness, or an internal tool keeps the reference voice in `prose.md`, since its reader has already committed and arrived looking for a fact.
+
+- Address the reader in second person. First-person plural needs an authoring organization as its antecedent, so a single-maintainer project has none to use.
+- Use contractions wherever the sentence reads better for one. Do not force them in.
+- Write with a point of view. State what the project chose and why, not a neutral survey of the options it passed over.
+- Ground a claim in something concrete rather than an adjective. A command, a number, or a named constraint carries more than a description of quality.
+- Be honest about limits. Naming what the project does not do reads as more credible, not less.
+
 ## Structure
 
 - H1 title, H2 major sections, H3 subsections. Maintain proper hierarchy for GitHub's auto-generated table of contents.

package/standards/skill.md

@@ -173,6 +173,18 @@ Without this skill, a session <observed failure>, <observed failure>.
 - When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
 - Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.
 
+### Deriving the branch slug
+
+Run `git branch --show-current` and replace every `/` with `-`. The result is `<slug>`. Anything reading a branch-derived name uses this transform, so two skills cannot spell it differently.
+
+A skill that persists output under `.claude/` carries the slug in the filename, which is what keeps parallel worktrees from overwriting each other's output.
+
+The empty result is a detached HEAD, and the skill picks one of three responses rather than inheriting a default. State the choice in the body, since the transform is shared and this is not.
+
+- Fall back to `latest`, so a read-only pass still writes somewhere predictable
+- Stop, when the skill commits or opens a pull request. There is no branch to put the work on, so `latest` would bury the problem instead of reporting it. State the stop in the skill's guards.
+- Fall through to the next source, when the slug is one candidate among several rather than the name of an output file
+
 ## Scripts
 
 - Use `scripts/` for operations that must be deterministic or repetitive
@@ -199,6 +211,8 @@ A standard reaches a skill by two routes, and a body that names only the first b
 - State the fallback once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the fallback at every mention is noise rather than instruction.
 - A guard on a standard's presence names the file and tests both paths before it stops. A guard that tests only `.claude/standards/` refuses to run in a plugin-only project that has the file, and a guard that tests the directory passes in the partial-install case it exists to catch.
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`. Only `${CLAUDE_SKILL_DIR}` is expanded before the body reaches the model. The other two leave the model to infer a base path, which it may resolve against the session cwd instead.
+- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in a standard and a citation in each body. Nothing catches a restatement that drifts, because the drift assertion covers generated copies and a hand-written one is not generated, so the guarantee is only that a single definition exists to correct.
+- Keep the trigger in the body and the procedure in the standard. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the standard cannot know it.
 
 ## Invocation
 

package/tooling/claude/reference.md

@@ -14,6 +14,7 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
+├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── GOV.md             ← retired. Removed by `aitk gov sync` if present from a prior install
 ├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `aitk claude setup`.
 ├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs.
@@ -32,6 +33,10 @@ Convert by hand, once per project:
 2. Run `aitk indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
 
+## Upgrading from a single-file diagram set
+
+A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
+
 ## Gitignore
 
 - `# Claude`: `.claude/.tmp/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`

package/tooling/claude/seeds/.claude/diagrams/index.md

@@ -0,0 +1,8 @@
+---
+title: Diagrams
+subtitle: Per-kind Mermaid views loaded on demand. Start with system context.
+---
+
+# Diagrams
+
+Per-kind Mermaid views loaded on demand. Start with system context.