@erclx/aitk 0.20.0 → 0.22.0

package/src/context/folders.ts

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import { INDEX_FILE, listIndexes } from '@/indexes/walk'
+
+/**
+ * Folder names under `.claude/` audited by default.
+ *
+ * The index-plus-entry contract on its own over-collects. `.claude/standards/`
+ * also carries a generated index beside entries with frontmatter, and auditing
+ * it would measure the consumed copy of `standards/` against a rule written for
+ * per-domain narrative. This list names the folders `standards/context.md`
+ * governs, and `--folder` admits another without an edit here.
+ */
+export const DEFAULT_FOLDERS: readonly string[] = [
+  'context',
+  'diagrams',
+  'wireframes',
+]
+
+export interface AuditedFolder {
+  /** Repo-relative folder path, used verbatim in every report line. */
+  readonly rel: string
+  readonly indexPath: string
+  /** Absolute paths of the folder's own entries, excluding its `index.md`. */
+  readonly entries: readonly string[]
+}
+
+/**
+ * Names the requested folders that actually exist, which is the citation
+ * check's scope.
+ *
+ * A skill or seed pointing into `.claude/wireframes/` is a live instruction for
+ * a project that carries the folder and says nothing about one that does not.
+ * Checking a path into an absent folder would fail eight shipped references
+ * 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]))]
+}
+
+async function readEntries(dir: string): Promise<string[]> {
+  const paths: string[] = []
+
+  for await (const name of new Bun.Glob('*.md').scan({
+    cwd: dir,
+    onlyFiles: true,
+    dot: true,
+  })) {
+    if (name === INDEX_FILE) continue
+    paths.push(resolve(dir, name))
+  }
+
+  return paths.sort()
+}
+
+/**
+ * Resolves the folders to audit under `root`.
+ *
+ * A named folder contributes its own entries plus those of every nested index
+ * folder beneath it, so a domain that outgrew one file and split is audited at
+ * the same grain as one that did not. Discovery of the nested folders runs
+ * through the shared walker, which is what keeps `.gitignore` and the vendored
+ * prune governing this scan as well as index regeneration.
+ *
+ * A requested folder that does not exist is dropped rather than reported. The
+ * default list names three folders and a project carrying one of them is the
+ * ordinary case.
+ */
+export async function resolveFolders(
+  root: string,
+  names: readonly string[] = DEFAULT_FOLDERS,
+): Promise<AuditedFolder[]> {
+  const folders: AuditedFolder[] = []
+
+  for (const name of names) {
+    const dir = resolve(root, '.claude', name)
+    if (!existsSync(`${dir}/${INDEX_FILE}`)) continue
+
+    const dirs = [dir, ...(await listIndexes(dir)).map(dirname)]
+
+    for (const each of [...new Set(dirs)].sort()) {
+      folders.push({
+        rel: relative(root, each),
+        indexPath: `${each}/${INDEX_FILE}`,
+        entries: await readEntries(each),
+      })
+    }
+  }
+
+  return folders
+}

package/src/context/index-drift.ts

@@ -0,0 +1,64 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { basename, dirname, resolve } from 'node:path'
+import type { AuditedFolder } from '@/context/folders'
+
+const ENTRY_LINK = /^-\s+\[[^\]]*\]\(([^)]+)\)/
+
+export interface FolderDrift {
+  readonly rel: string
+  /** Entry files present in the folder that the index does not link. */
+  readonly unlisted: readonly string[]
+  /** Names the index links that resolve to nothing on disk. */
+  readonly missing: readonly string[]
+}
+
+/** Collects the link targets of an index's catalog bullets. */
+export function listedTargets(source: string): string[] {
+  const targets: string[] = []
+
+  for (const line of source.split('\n')) {
+    const match = line.match(ENTRY_LINK)
+    if (match) targets.push(match[1])
+  }
+
+  return targets
+}
+
+/**
+ * Compares one folder's index against its siblings in both directions.
+ *
+ * Both halves are reported because they fail differently. An unlisted entry is
+ * invisible to a session reading the catalog to choose what to open, while a
+ * listed name with no file sends one to a path that opens nothing. Neither
+ * surfaces from reading the index alone.
+ */
+export async function auditFolder(folder: AuditedFolder): Promise<FolderDrift> {
+  const dir = dirname(folder.indexPath)
+  const source = await readFile(folder.indexPath, 'utf8')
+  const targets = listedTargets(source)
+
+  // A sub-catalog is linked as `<name>/index.md` and its entries are audited
+  // as their own folder, so only the leading segment is compared here.
+  const listed = new Set(targets.map((target) => target.split('/')[0]))
+
+  const unlisted = folder.entries
+    .map((path) => basename(path))
+    .filter((name) => !listed.has(name))
+
+  const missing = targets.filter((target) => !existsSync(resolve(dir, target)))
+
+  return { rel: folder.rel, unlisted, missing }
+}
+
+export async function auditIndexes(
+  folders: readonly AuditedFolder[],
+): Promise<FolderDrift[]> {
+  const drift: FolderDrift[] = []
+
+  for (const folder of folders) {
+    drift.push(await auditFolder(folder))
+  }
+
+  return drift
+}

package/standards/index.md

@@ -18,5 +18,5 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
-- [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, commits, and tags
+- [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/prose.md

@@ -74,10 +74,14 @@ 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
+## Pre-publish 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.
 
+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.
+
+### Banned characters
+
 Scan the drafted text and rewrite each occurrence:
 
 - `—` (em dash): split into two sentences, or use a comma
@@ -85,7 +89,17 @@ Scan the drafted text and rewrite each occurrence:
 
 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.
+### Phase labels
+
+The versioning standard beside this file holds the label rule and the table of surfaces. Read it at scan time rather than working the format from memory.
+
+Scope this check by destination. Text published to a remote takes it. Text scanned on its way into the repository, where the reader has the task board, takes the character checks alone.
+
+### An unreadable source
+
+Stop and name the source when one this scan reaches for cannot be read. Do not scan what resolved and report the result.
+
+A run that covers half its sources and says nothing is worse than one that visibly did not happen, because the surfaces running this scan are the ones that describe themselves as the only gate. A clean result from a half-run scan is read as coverage.
 
 ## Frontmatter descriptions
 

package/standards/versioning.md

@@ -1,6 +1,6 @@
 ---
 title: Versioning reference
-description: Phase label vs semver discipline across tasks, PRs, commits, and tags
+description: Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 ---
 
 # Versioning reference
@@ -31,6 +31,9 @@ External release identity used in git tags and release notes. Independent of pha
 | `.claude/tasks/`          | yes          | no                                  |
 | Chat with the operator    | yes          | no                                  |
 | PR titles                 | no           | only when the PR cuts a release     |
+| PR bodies                 | no           | only when the PR cuts a release     |
+| Review comments           | no           | only when referencing a release     |
+| Issue titles and bodies   | no           | only when referencing a release     |
 | Commit messages           | no           | only when the commit cuts a release |
 | Git tags                  | no           | yes                                 |
 | README and `CHANGELOG.md` | no           | yes                                 |
@@ -41,6 +44,13 @@ External release identity used in git tags and release notes. Independent of pha
 - Commit subjects do not embed phase labels.
 - Git tags use semver only. Phase labels never become tags.
 - A PR that cuts a release may reference its semver tag in the title or body. Phase labels still do not appear.
+- PR bodies, review comments, and issue text name the change itself, never the internal stream that scheduled it. Describe the work rather than the label it was planned under.
+
+## Pre-publish check
+
+Text bound for a remote is checked for phase labels against the finished draft, before it is sent. A body, comment, or title reaches a reader who has no task board, so a label that survives to publication cannot be resolved by anyone downstream.
+
+The surface publishing the text is the last gate on it. Where no automated check covers that surface, the author performs the check as an explicit step rather than relying on having read this file while drafting.
 
 ## Why