@erclx/aitk 3.9.0 → 3.11.0

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/tooling/base/manifest.toml

@@ -23,8 +23,6 @@ packages = [
 "format" = "prettier --write --log-level warn --ignore-path .gitignore --ignore-path .prettierignore . && shfmt --write --indent 2 scripts/"
 "prepare" = "husky"
 "check" = "./scripts/verify.sh"
-"clean" = "./scripts/clean.sh"
-"update" = "./scripts/update.sh"
 
 [gitignore]
 "# System" = [".DS_Store"]

package/tooling/base/reference.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and three maintenance scripts. Every other stack extends it, so a decision made here is one every stack inherits.
+The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and one maintenance script. Every other stack extends it, so a decision made here is one every stack inherits.
 
 A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `docs/target-projects.md` carries the recipe.
 
@@ -18,7 +18,7 @@ Golden config files live in `tooling/base/configs/` and are copied into the targ
 - `.github/workflows/verify.yml`: runs on pull requests targeting `main` and on `workflow_dispatch`.
 - `.github/pull_request_template.md`: `## Summary`, `## Key Changes`, `## Technical Context`, `## Testing`.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for Prettier, cspell, shfmt, and shellcheck.
-- `scripts/verify.sh`, `scripts/clean.sh`, `scripts/update.sh`: the maintenance entry points behind `check`, `clean`, and `update`.
+- `scripts/verify.sh`: the maintenance entry point behind `check`.
 
 ## What ships as user-owned seeds
 
@@ -86,13 +86,13 @@ Sticky negative knowledge. Do not relearn.
 
 ## CLI
 
-| Script                 | What it does                                                                                                                                                                                           |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `bun run check`        | Full verification suite via `scripts/verify.sh`. Runs `format` first to auto-fix drifted code, then asserts. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
-| `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                                                                                  |
-| `bun run check:spell`  | Runs cspell across every file, with context on failures                                                                                                                                                |
-| `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                                                                                    |
-| `bun run format`       | Writes prettier and shfmt formatting in place                                                                                                                                                          |
-| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                                                                                            |
-| `bun run clean`        | Removes `node_modules/`, clears the bun cache, reinstalls fresh                                                                                                                                        |
-| `bun run update`       | Runs `bun update --interactive`, then `verify.sh` with `VERIFY_NESTED=true`                                                                                                                            |
+| Script                 | What it does                                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `bun run check`        | Repairs a checkout via `scripts/verify.sh`. Honors `VERIFY_NESTED=true` to suppress timeline boundaries when another script calls it. |
+| `bun run check:format` | Asserts prettier and shfmt formatting without writing                                                                                 |
+| `bun run check:spell`  | Runs cspell across every file, with context on failures                                                                               |
+| `bun run check:shell`  | Runs shellcheck at warning severity                                                                                                   |
+| `bun run format`       | Writes prettier and shfmt formatting in place                                                                                         |
+| `bun run prepare`      | Initializes husky hooks, run automatically on `bun install`                                                                           |
+
+`bun run check` repairs a checkout rather than gating one. It runs `format` first to auto-fix drifted code, then asserts only what the formatters could not fix. The pull request workflow calls `check:format`, `check:spell`, and `check:shell` directly, and those three are the gate.

package/tooling/base/seeds/.claude/context/development.md

@@ -21,12 +21,10 @@ Owns how the project runs on a developer machine: installing the toolchain, the
 
 ## Scripts
 
-| Command          | Purpose                                              |
-| ---------------- | ---------------------------------------------------- |
-| `bun run check`  | Full verification. Auto-formats, then asserts clean. |
-| `bun run format` | Auto-fix prettier and shfmt formatting.              |
-| `bun run clean`  | Wipe `node_modules/`, clear bun cache, reinstall.    |
-| `bun run update` | Interactive `bun update` followed by verification.   |
+| Command          | Purpose                                                                        |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `bun run check`  | Repairs locally. Auto-formats, then asserts what the formatters could not fix. |
+| `bun run format` | Auto-fix prettier and shfmt formatting.                                        |
 
 ## Shell scripts
 

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
-```

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

@@ -1,95 +0,0 @@
----
-title: Issue reference
-description: GitHub issue title, labels, and body conventions
-consumers: git-issue
----
-
-# Issue reference
-
-## Scope
-
-Governs a tracker issue: its title, its labels, and the sections its body carries.
-
-Does not govern:
-
-- Pull request title and body: `pr.md`
-- Whether a phase label may appear in issue text: `versioning.md`
-- Voice, rhythm, and sentence construction in issue prose: the `write-human` skill
-- Punctuation, formatting, and banned words in issue prose: `markdown.md`
-
-## Title
-
-- Format: `<type>: <subject>`
-- Type is `bug` or `task`. Lowercase the type and the first word of the subject.
-- Length: 72 characters maximum, no trailing period.
-
-## Labels
-
-- Apply `bug` for a defect and `enhancement` for a task or improvement.
-- Both are GitHub default labels. A label that does not exist makes `gh` reject the issue. Create it once with `gh label create`.
-- One label per issue unless a second genuinely applies.
-
-## Content
-
-- Use imperative mood and describe the actual defect or work, not that something is wrong.
-- Do not open with "This issue," "I want," or "We should."
-- Do not use buzzwords or speculative future scope.
-- State observable behavior for a bug, not a guessed cause.
-
-## Sections
-
-- `## Summary`: one line naming what and why.
-- `## Details`: for a bug, what happens versus what is expected. For a task, what to build.
-- `## Context`: for a bug, repro steps or commands. For a task, the driving reason, or `none`.
-- `## Proposed` (optional): one line naming a fix or approach. Omit when open.
-
-## Formatting
-
-- End every bullet with a period.
-- Keep each section to one or two lines.
-
-## Examples
-
-### Correct (bug)
-
-```markdown
-## Summary
-
-Fix the feedback CLI so it applies the `feedback` label.
-
-## Details
-
-`aitk feedback --github` opens an issue with no label, so `toolkit-triage` never lists it.
-
-## Context
-
-Run a piped `aitk feedback --github`, then check the issue carries no `feedback` label.
-
-## Proposed
-
-Pass `--label feedback` through the shared issue helper.
-```
-
-### Correct (task)
-
-```markdown
-## Summary
-
-Add a git-issue skill so a session can file an issue on the current repo.
-
-## Details
-
-Format an issue from session context and file it with `gh issue create`, next to git-pr in the git family.
-
-## Context
-
-The toolkit-issue skill only files on the toolkit repo. A general path is needed for target projects.
-```
-
-### Incorrect
-
-```markdown
-## Summary
-
-This issue is about the feedback system being kind of broken, and we should probably make it more robust.
-```

package/claude/skills/git-pr/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
-```