@erclx/aitk 3.10.0 → 3.11.0

package/src/commands/claude.ts

@@ -20,6 +20,7 @@ import {
   REQUIREMENT_SECTIONS,
   type SkillFinding,
   type SkillsAudit,
+  type SkillsAuditRefusal,
 } from '@/claude/skills-audit'
 import {
   type RoutingRefusal,
@@ -862,8 +863,11 @@ async function runSkillsAudit(
 
   if (report.corpora.length === 0) {
     return refuseAudit(
+      'no-corpus',
       `No skill corpus under ${root}. Looked for ${CORPORA.join(' and ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -910,16 +914,26 @@ async function runSkillsAudit(
   return auditExitCode(report)
 }
 
-function refuseAudit(message: string, gateOnly: boolean): number {
+function refuseAudit(
+  reason: SkillsAuditRefusal,
+  message: string,
+  gateOnly: boolean,
+  root: string,
+  emitJson: boolean,
+): number {
   if (gateOnly) {
     frameError(message)
-    return 1
+  } else {
+    intro('aitk claude skills audit')
+    logStep('Refused')
+    logWarn(message)
+    outro()
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
   }
 
-  intro('aitk claude skills audit')
-  logStep('Refused')
-  logWarn(message)
-  outro()
   return 1
 }
 

package/src/commands/comments.ts

@@ -88,6 +88,12 @@ async function runScan(
     logStep('Refused')
     logWarn(languages)
     outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({ root, reason: 'bad-languages', message: languages })}\n`,
+      )
+    }
     return 1
   }
 

package/src/commands/context.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import {
+  type ContextAuditRefusal,
   type EntryReport,
   governsContent,
   type LengthCause,
@@ -157,12 +158,17 @@ async function runAudit(
   // short a required section, which is the pass a gate exists to prevent.
   if (gateOnly && widened) {
     return refuse(
+      'conflicting-options',
       '--citations-only runs the citation check alone, so --gate would widen the gate to findings the run never measures. Pass one.',
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
-  if (typeof names === 'string') return refuse(names, gateOnly)
+  if (typeof names === 'string') {
+    return refuse('bad-folder-list', names, gateOnly, root, opts.json ?? false)
+  }
 
   // The root base is opt-in. A target carrying a root `wireframes/` would
   // otherwise be audited against a standard it never adopted, on a bare run
@@ -173,8 +179,11 @@ async function runAudit(
   })
   if (folders.length === 0) {
     return refuse(
+      'no-folders',
       `No audited folder found ${named ? 'under .claude/ or the project root' : 'under .claude/'}. Looked for: ${names.join(', ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -190,16 +199,22 @@ async function runAudit(
   const cited = presentNames(folders)
   if (gateOnly && cited.length === 0) {
     return refuse(
+      'no-citation-scope',
       `The citation check spells the .claude/ prefix and no audited folder resolved there. Looked for: ${names.join(', ')}.`,
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
   const citations = await auditCitations(root, cited)
   if (citations.kind === 'unavailable') {
     return refuse(
+      'no-git',
       'git could not list the tree, so no citation was checked. Run inside a git repository.',
       gateOnly,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -308,16 +323,26 @@ async function runAudit(
   return gating ? EXIT_GATE : 0
 }
 
-function refuse(message: string, gateOnly: boolean): number {
+function refuse(
+  reason: ContextAuditRefusal,
+  message: string,
+  gateOnly: boolean,
+  root: string,
+  emitJson: boolean,
+): number {
   if (gateOnly) {
     frameError(message)
-    return 1
+  } else {
+    intro('aitk context audit')
+    logStep('Refused')
+    logWarn(message)
+    outro()
+  }
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
   }
 
-  intro('aitk context audit')
-  logStep('Refused')
-  logWarn(message)
-  outro()
   return 1
 }
 

package/src/commands/gov.ts

@@ -506,12 +506,12 @@ function runTestOrder(opts: TestOrderOptions): number {
   if (report.kind === 'unreadable') {
     intro('aitk gov test-order')
     logStep('Refused')
-    logError(report.reason)
+    logError(report.message)
     outro()
 
     if (emitJson) {
       process.stdout.write(
-        `${JSON.stringify({ ok: false, reason: report.reason })}\n`,
+        `${JSON.stringify({ root, reason: report.reason, message: report.message })}\n`,
       )
     }
 

package/src/commands/markdown.ts

@@ -2,7 +2,7 @@ import { readFile } from 'node:fs/promises'
 import { resolve } from 'node:path'
 import type { Command } from 'commander'
 import { BAN_SETS, emptyBanSets } from '@/markdown/bans'
-import { resolveMarkdown } from '@/markdown/files'
+import { type MarkdownAuditRefusal, resolveMarkdown } from '@/markdown/files'
 import { isGating } from '@/markdown/gate'
 import {
   type BanFinding,
@@ -119,15 +119,21 @@ async function runAudit(
 
   if (scope.kind === 'unavailable') {
     return refuse(
+      'no-git',
       'git could not list the tree, so no corpus was built. Run inside a git repository.',
+      root,
+      opts.json ?? false,
     )
   }
 
   if (scope.files.length === 0) {
     return refuse(
+      paths.length === 0 ? 'no-markdown' : 'no-match',
       paths.length === 0
         ? 'No markdown file in the tree.'
         : `No markdown file matched: ${scope.unmatched.join(', ')}`,
+      root,
+      opts.json ?? false,
     )
   }
 
@@ -203,11 +209,21 @@ async function runAudit(
   return gating ? EXIT_GATE : 0
 }
 
-function refuse(message: string): number {
+function refuse(
+  reason: MarkdownAuditRefusal,
+  message: string,
+  root: string,
+  emitJson: boolean,
+): number {
   intro('aitk markdown audit')
   logStep('Refused')
   logWarn(message)
   outro()
+
+  if (emitJson) {
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
+  }
+
   return EXIT_REFUSED
 }
 

package/src/context/audit.ts

@@ -15,6 +15,22 @@ import { isStubSeed } from '@/seed-marker'
  * any markdown file, so they are stated at the attribute tier and measured by
  * `aitk markdown audit` rather than here.
  */
+/**
+ * Every reason `aitk context audit` refuses for.
+ *
+ * `no-folders` is the one ordinary absence: a project that never adopted
+ * `.claude/context/`, `.claude/diagrams/`, or `.claude/wireframes/` names no
+ * corpus this audit can measure, the same state `no-skills` reads for the
+ * skill corpora. The other four are a malformed invocation or a checkout git
+ * cannot read, which stay a break rather than an absence.
+ */
+export type ContextAuditRefusal =
+  | 'conflicting-options'
+  | 'bad-folder-list'
+  | 'no-folders'
+  | 'no-citation-scope'
+  | 'no-git'
+
 export const LENGTH_CHECKPOINT = 150
 
 /**

package/src/gov/test-order.ts

@@ -44,6 +44,21 @@ export interface Scope {
   readonly testSuffixes: readonly string[]
 }
 
+/**
+ * Every reason `aitk gov test-order` refuses for.
+ *
+ * None is an ordinary absence. A depth-1 checkout falls back to the root
+ * commit and reports zero rather than reaching any of these, so what remains
+ * is a repository with no commit at all or a git operation that failed
+ * outright, both a broken checkout rather than a target's ordinary state.
+ */
+export type TestOrderRefusal =
+  | 'no-history'
+  | 'no-log'
+  | 'no-tree'
+  | 'bad-base'
+  | 'no-base'
+
 export type TestOrderReport =
   | {
       readonly kind: 'measured'
@@ -56,7 +71,11 @@ export type TestOrderReport =
       /** Changed paths outside the pairing's reach, named rather than counted. */
       readonly ignored: readonly string[]
     }
-  | { readonly kind: 'unreadable'; readonly reason: string }
+  | {
+      readonly kind: 'unreadable'
+      readonly reason: TestOrderRefusal
+      readonly message: string
+    }
 
 export interface TestOrderOptions {
   /** The far side of the range, defaulting to the merge base against the trunk. */
@@ -258,7 +277,8 @@ export function readTestOrder(
   if (head === undefined) {
     return {
       kind: 'unreadable',
-      reason: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
+      reason: 'no-history',
+      message: `No git history under ${root}. History is the only surface carrying the ordering, so there is nothing to read.`,
     }
   }
 
@@ -277,7 +297,8 @@ export function readTestOrder(
   if (log === undefined) {
     return {
       kind: 'unreadable',
-      reason: `Reading history between ${base} and HEAD failed under ${root}.`,
+      reason: 'no-log',
+      message: `Reading history between ${base} and HEAD failed under ${root}.`,
     }
   }
 
@@ -285,7 +306,8 @@ export function readTestOrder(
   if (tree === undefined) {
     return {
       kind: 'unreadable',
-      reason: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
+      reason: 'no-tree',
+      message: `Reading the tree at ${base} failed under ${root}. Without it a test written before the range reads as absent.`,
     }
   }
 
@@ -323,13 +345,14 @@ function resolveBase(
   root: string,
   ref: string | undefined,
   head: string,
-): string | { kind: 'unreadable'; reason: string } {
+): string | { kind: 'unreadable'; reason: TestOrderRefusal; message: string } {
   if (ref !== undefined) {
     const resolved = revParse(root, ref)
     if (resolved === undefined) {
       return {
         kind: 'unreadable',
-        reason: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
+        reason: 'bad-base',
+        message: `Ref ${ref} resolves to no commit in ${root}. Pass a commit this tree carries.`,
       }
     }
     return resolved
@@ -345,7 +368,8 @@ function resolveBase(
   if (rootCommits === undefined || rootCommits === '') {
     return {
       kind: 'unreadable',
-      reason: `No base resolves against ${root}. Fetch origin or pass --base.`,
+      reason: 'no-base',
+      message: `No base resolves against ${root}. Fetch origin or pass --base.`,
     }
   }
 

package/src/markdown/files.ts

@@ -19,6 +19,16 @@ export type FileScope =
     }
   | { readonly kind: 'unavailable' }
 
+/**
+ * Every reason `aitk markdown audit` refuses for.
+ *
+ * None is an ordinary absence. `no-git` is a broken checkout the way it is
+ * for the secret scan, and a tree tracked by git carrying no markdown file at
+ * all, or an argument matching none, is a corpus this run could not build
+ * rather than a target that adopted none of the convention this check reads.
+ */
+export type MarkdownAuditRefusal = 'no-git' | 'no-markdown' | 'no-match'
+
 function isDirectory(path: string): boolean {
   try {
     return statSync(path).isDirectory()

package/src/records/backup.ts

@@ -32,6 +32,7 @@ export const BACKED_FOLDERS = [
   'intake',
   'memory',
   'plans',
+  'proposals',
   'review',
   'tasks',
   'teach',

package/src/records/validate.ts

@@ -1115,9 +1115,7 @@ export async function validateRecords(
     )
   }
 
-  // The walk stays flat, matching install and the catalog. `standards/bundled/`
-  // is a subfolder whose members are named for the skill that reads them rather
-  // than for a path they govern, so the derivation below reports every one.
+  // The walk stays flat, matching install and the catalog.
   if (kind === 'standards') {
     return validateFiles(
       dir,

package/{claude/skills/git-split/references → standards}/branch.md

@@ -1,7 +1,6 @@
 ---
 title: Branch reference
 description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-worktree
 ---
 
 # Branch reference

package/{claude/skills/git-commit/references → standards}/commit.md

@@ -1,7 +1,6 @@
 ---
 title: Commit reference
 description: Commit message format and type conventions
-consumers: git-commit, git-stage
 ---
 
 # Commit message reference

package/{claude/skills/claude-teach/references → standards}/glossary.md

@@ -1,7 +1,6 @@
 ---
 title: Glossary reference
 description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
-consumers: claude-teach
 ---
 
 # Glossary reference

package/standards/index.md

@@ -8,14 +8,19 @@ subtitle: Reference docs for consistent authoring across the toolkit and target
 Reference docs for consistent authoring across the toolkit and target projects.
 
 - [Architecture reference](architecture.md): Shape and content rules for .claude/ARCHITECTURE.md
+- [Branch reference](branch.md): Branch naming format and type conventions
+- [Commit reference](commit.md): Commit message format and type conventions
 - [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): Shape and content rules for .claude/diagrams/<kind>.md files
+- [Glossary reference](glossary.md): Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
 - [Groundwork reference](groundwork.md): Folder layout, reserved numbering, frontmatter and dating, required file contents, and conventions for a measurement track
 - [Intake reference](intake.md): Folder layout, reserved index number, frontmatter and dating, the item template, the answer contract, and retrieval
+- [Issue reference](issue.md): GitHub issue title, labels, and body conventions
 - [Markdown reference](markdown.md): Headings, paragraph and list structure, code spans, the date form, punctuation, emphasis, file references, banned words, and frontmatter wording
 - [Memory reference](memory.md): Filename and type prefix, frontmatter, the body shape per type, links between entries, and the lifecycle from write to retire
 - [Plan reference](plan.md): Filename and slug, required sections, the suggested-and-answer contract, and the lifecycle from the live folder to the archive
+- [Pull request reference](pr.md): Pull request title and body conventions
 - [Publish reference](publish.md): Scan an author runs against finished text, the cross-reference form each destination takes, and the response to an unreadable source
 - [Readme reference](readme.md): Readme voice, structure, and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
@@ -23,6 +28,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Session map reference](session.md): Filename and location, the sections a handoff carries, the write and read procedures, and how a role extends it
 - [Claude skill reference](skill.md): Claude skill structure and authoring rules
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
+- [Snippet reference](snippets.md): Snippet reference and authoring conventions
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
 - [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission and learning-record formats for a learning workspace

package/standards/{bundled/issue.md → issue.md}

@@ -1,7 +1,6 @@
 ---
 title: Issue reference
 description: GitHub issue title, labels, and body conventions
-consumers: git-issue
 ---
 
 # Issue reference

package/standards/{bundled/pr.md → pr.md}

@@ -1,7 +1,6 @@
 ---
 title: Pull request reference
 description: Pull request title and body conventions
-consumers: git-split, git-pr
 ---
 
 # Pull request reference

package/standards/{bundled/snippets.md → snippets.md}

@@ -1,7 +1,6 @@
 ---
 title: Snippet reference
 description: Snippet reference and authoring conventions
-consumers: create-snippet
 ---
 
 # Snippet reference

package/claude/skills/claude-worktree/references/branch.md

@@ -1,60 +0,0 @@
----
-title: Branch reference
-description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-worktree
----
-
-# Branch reference
-
-## Scope
-
-Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
-
-Does not govern:
-
-- Commit subject format, which shares the type vocabulary: `commit.md`
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in a branch name: `versioning.md`
-- Deriving a slug from a branch name for use in an output filename: `slug.md`
-
-## Format
-
-- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
-- Length: 50 characters maximum
-- Casing: kebab-case only, no underscores or camelCase
-- Description: 2 words maximum, 3 only when genuinely needed for specificity
-- Capture the core change, not the commit message verbatim
-- For branches with multiple commits, use the unifying concern as the description.
-- Do not duplicate type in description (e.g., `feat/feature-login`)
-
-## Types
-
-- `feat`: new feature or capability
-- `fix`: bug fix
-- `refactor`: structural changes (not a fix or feature)
-- `docs`: documentation only (README)
-- `chore`: maintenance tasks (deps, tooling, configs)
-- `perf`: performance improvements
-- `test`: add or modify tests
-- `style`: code formatting (whitespace, semicolons)
-- `build`: build system changes (webpack, npm scripts)
-- `ci`: CI/CD pipeline changes (GitHub Actions)
-- `revert`: revert a previous commit
-
-## Examples
-
-### Correct
-
-```plaintext
-feat/jwt-expiration                    # clear feature scope
-fix/AUTH-123-connection-pool           # includes ticket ID
-refactor/remove-deprecated-endpoints   # clear refactor intent
-```
-
-### Incorrect
-
-```plaintext
-feature/auth_stuff                                        # wrong type + underscore
-feat/feature-add-login                                    # duplicates type in description
-fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
-```

package/claude/skills/create-snippet/references/snippets.md

@@ -1,78 +0,0 @@
----
-title: Snippet reference
-description: Snippet reference and authoring conventions
-consumers: create-snippet
----
-
-# Snippet reference
-
-## Scope
-
-Governs a snippet file: what one is for, whether a prompt qualifies as one, how it is invoked, and the structure of its body.
-
-Does not govern:
-
-- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
-- Voice, rhythm, and sentence construction in snippet prose: the `write-human` skill
-- Punctuation, formatting, and word choice in snippet prose: `markdown.md`
-
-## What a snippet is
-
-A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
-
-## Admission
-
-Two tests decide whether a prompt becomes a snippet, and both have to pass. Apply them when adding one and when auditing the catalog.
-
-- Cadence: a prompt invoked many times across sessions qualifies. A one-shot audit, migration, or bootstrap prompt does not, and belongs in notes outside the catalog.
-- Audience: a prompt the consuming project would invoke ships in `snippets/`. One only the authoring repository can run stays outside every installable folder, which is a rule for a repository that authors snippets for others rather than for one that only consumes them.
-
-A subfolder under `snippets/` names where a prompt is invoked rather than what it is about. A prompt that reads or writes the project's own files goes in a folder, and one carrying its whole context in the message goes at the root.
-
-Overlapping a skill that does the same job is not disqualifying on its own. A snippet fires when a person asks for it by name and a skill fires on a description match, so the two coexist when those paths differ and the outputs do. Record the reason where the project keeps its decisions, or drop the snippet.
-
-## Invocation channels
-
-- Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
-- Claude Code terminal: prefix the install path with `@` (e.g. `@.claude/snippets/claude/feature`)
-- Snippets install preserving the source folder structure. A snippet at `claude/edit.md` installs as `.claude/snippets/claude/edit.md` and is invoked as `@.claude/snippets/claude/edit`
-
-## Use patterns
-
-- Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
-- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `claude-feature`, then add the feature name or extra constraints)
-- Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
-
-## Authoring
-
-- One focused purpose per snippet. If it needs headers or multiple goals, use a system prompt instead.
-- Self-contained. No references to external files or assumed prior context.
-- No user fill-in placeholders. If a value depends on context, the user adds it after invocation.
-- Plain markdown only. No YAML frontmatter, no headers, no nested structure.
-- Filename is the slug: kebab-case, no capitals, no underscores
-
-## Structure
-
-- Lead with a verb. Open with an imperative that states the job immediately.
-- One instruction per sentence. Do not stack multiple actions into one sentence.
-- For sequential steps, use a numbered list with one action per item.
-- When the output has a fixed shape, show it in a fenced code block with a language identifier.
-- Put constraints and exclusions last, not inline with the main instructions.
-
-## Examples
-
-### Correct
-
-```markdown
-I want to implement the following. Scan relevant files and list conflicts. Do not implement. # user adds feature after invocation
-Scan relevant files and list conflicts. Do not implement. # run-as-is, no context needed
-```
-
-### Incorrect
-
-```markdown
-I want to implement: <feature or task name> # redundant fill-in, add context after invocation instead
-See ARCHITECTURE.md before starting. # external dependency, not self-contained
-
-## Overview\n## Steps # headers belong in a system prompt, not a snippet
-```

package/claude/skills/git-branch/references/branch.md

@@ -1,60 +0,0 @@
----
-title: Branch reference
-description: Branch naming format and type conventions
-consumers: git-branch, git-split, git-pr, claude-worktree
----
-
-# Branch reference
-
-## Scope
-
-Governs a git branch name: its structure, its length, and the type vocabulary it draws from.
-
-Does not govern:
-
-- Commit subject format, which shares the type vocabulary: `commit.md`
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in a branch name: `versioning.md`
-- Deriving a slug from a branch name for use in an output filename: `slug.md`
-
-## Format
-
-- Structure: `<type>/<description>` or `<type>/<ticket>-<description>`
-- Length: 50 characters maximum
-- Casing: kebab-case only, no underscores or camelCase
-- Description: 2 words maximum, 3 only when genuinely needed for specificity
-- Capture the core change, not the commit message verbatim
-- For branches with multiple commits, use the unifying concern as the description.
-- Do not duplicate type in description (e.g., `feat/feature-login`)
-
-## Types
-
-- `feat`: new feature or capability
-- `fix`: bug fix
-- `refactor`: structural changes (not a fix or feature)
-- `docs`: documentation only (README)
-- `chore`: maintenance tasks (deps, tooling, configs)
-- `perf`: performance improvements
-- `test`: add or modify tests
-- `style`: code formatting (whitespace, semicolons)
-- `build`: build system changes (webpack, npm scripts)
-- `ci`: CI/CD pipeline changes (GitHub Actions)
-- `revert`: revert a previous commit
-
-## Examples
-
-### Correct
-
-```plaintext
-feat/jwt-expiration                    # clear feature scope
-fix/AUTH-123-connection-pool           # includes ticket ID
-refactor/remove-deprecated-endpoints   # clear refactor intent
-```
-
-### Incorrect
-
-```plaintext
-feature/auth_stuff                                        # wrong type + underscore
-feat/feature-add-login                                    # duplicates type in description
-fix/DB-456-fix-the-database-connection-pool-memory-leak   # exceeds 50 chars + verbatim message
-```