@erclx/aitk 3.35.0 → 3.36.0

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

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

package/docs/agents/markdown-audit.md

@@ -61,7 +61,7 @@ Two ban shapes stay unmeasured and the report says so on every run. A multi-word
 
 ### Bullets, paragraphs, and depth
 
-Bullet weight and depth are the checks that moved off `aitk context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero and ending in a colon, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
+Bullet weight and depth are the checks that moved off `aitk context audit`, carrying what they measured at the time. A top-level bullet reports past roughly 400 characters with continuation lines folded in and nested items left out. A run reports past roughly 40 rendered lines, measured at 80 columns, where a heading breaks one and so does a bold section marker taking the whole line at column zero, either ending in a colon, or holding one whole code span at any width, or running to 20 characters or fewer, skipping fenced blocks and exempting a flat peer list averaging under 130 characters a bullet and a run that is entirely table rows. Each file reports its longest run alone, so a second run past the checkpoint in the same file is never named.
 
 Every weight and depth measure counts the text a reader is shown. A link reduces to its anchor text and an autolink drops whole, since no reader is shown either destination. A backticked path stays counted, which is where these measures part from the ban scan above: that one blanks a code span so a standard quoting its own banned character does not report itself, and discounting the same span here would under-report a paragraph carrying several. One file holds both span sets and each answers its own question.
 
@@ -136,7 +136,7 @@ Measured at `4b7b13a2` across 444 files with the paragraph checkpoint at 600: 8
 
 The ban half reached zero, which was the precondition the gate waited on, and it was re-measured against the same corpus at the moment the gate landed. Three sweep slices then took the structural half, and the corpus reports 1 heavy bullet and 22 heavy paragraphs across 6 files on 2026-08-06, every one on a ground the triage record holds as exempt.
 
-Depth is the one measure no slice triaged, so its figure moved with the sweep rather than with the corpus. The break rule widened to bold section markers on 2026-08-28, which drops the count again with no edit to any file, so the 41 above reads against a rule the command no longer runs. Read all four structural counts from a run rather than from this paragraph.
+Depth is the one measure no slice triaged, so its figure moved with the sweep rather than with the corpus. The break rule widened to bold section markers on 2026-08-28 and again to the colon-less ones the same day, and each drop came with no edit to any file, so the 41 above reads against a rule the command no longer runs. Read all four structural counts from a run rather than from this paragraph.
 
 ### What a hit asks of an author
 

package/governance/rules/ci/700-ci-workflow.md

@@ -0,0 +1,44 @@
+---
+description: Enforce GitHub Actions job naming, granularity, dependency wiring, and bun pinning
+paths:
+  - '.github/workflows/**'
+---
+
+# CI workflow standards
+
+## Triggers and pinning
+
+- Include `workflow_dispatch` alongside the primary trigger on every workflow.
+- Pin every action to a major version tag. Never `@latest` or `@main`.
+- Run every job on `ubuntu-latest`.
+
+## Job naming
+
+- Name every job as an emoji followed by a title, such as `🛡️ Checks`, `🧪 Unit Tests`, `📦 Build Check`, `🎭 E2E Tests`, or `🚀 Deploy`.
+
+## Job granularity
+
+- Fold static analysis, unit tests, and build into one job while the gate runs under two minutes end to end.
+- Split them into parallel jobs once a run log puts the gate past two minutes.
+- Give E2E, release, and deploy a job each from the start.
+
+## Job dependencies
+
+- Use `needs` for a data dependency, where a job consumes another job's artifact, or for a job whose cost is prohibitive against the gate in front of it. Leave every other job unwired so it runs in parallel.
+- Gate E2E on the job that uploads the build artifact.
+- Gate release and deploy on E2E.
+- Emit a deploy, publish, or release job with a placeholder step and name what the caller fills in. Never guess a deploy command.
+
+## Artifacts
+
+- Upload an artifact on `if: failure()` alone, with `retention-days: 7`.
+
+## Bun stack
+
+- Use `oven-sh/setup-bun@v2` with `bun-version: latest`.
+- Install with `bun install --frozen-lockfile`.
+- Key the Playwright browser cache on the Playwright version string, never a static key.
+
+## Authority
+
+- Load the `aitk:ci-workflow` skill for the workflow template and the per-project adaptation. Report it rather than proceeding silently when the skill does not resolve.

package/governance/rules/core/070-planning.md

@@ -14,4 +14,5 @@ description: Enforce planning standards before implementation
 - Write or update tests as part of every implementation plan.
 - Write the test for a behavior before the code that implements it. Confirm visual output after implementing it, not before.
 - Run `aitk gov test-order` before shipping a branch. Fix what it names as reaching history ahead of its test.
+- Load the `aitk:systematic-debugging` skill before proposing a fix for a failing test, a surfaced bug, or behavior nobody has explained yet, and report it rather than proceeding silently when the skill does not resolve.
 - Do not modify code without a confirmed plan.

package/governance/stacks/base.toml

@@ -1,6 +1,8 @@
 extends = ""
-# All three folders whole. Every rule authored under them ships to a base
+# All four folders whole. Every rule authored under them ships to a base
 # consumer, so adding one is a single edit rather than a file and a name here.
 # `snippets` carries the `@`-reference convention rule, which lost its only
-# other delivery path when `aitk snippets install` retired.
-rules = ["core", "claude", "snippets", "120-bash"]
+# other delivery path when `aitk snippets install` retired. `ci` carries the
+# workflow rule, whose glob is the only inbound route to the `ci-workflow`
+# skill.
+rules = ["core", "claude", "snippets", "ci", "120-bash"]

package/package.json

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

package/src/commands/markdown.ts

@@ -520,7 +520,7 @@ function reportDepth(
     'A run that is entirely table rows is excluded too, since a heading inside a table splits the table rather than the run.',
   )
   logInfo(
-    'A heading breaks a run and so does a bold section marker at column zero ending in a colon, such as a line reading only Risks in bold. A colon-less or indented one stays prose.',
+    'A heading breaks a run and so does a bold section marker at column zero, such as a line reading only Risks in bold. A colon-less one breaks when it holds one whole code span, or when it runs to 20 characters or fewer, and an indented one stays prose.',
   )
 
   const over = reports

package/src/markdown/structure.ts

@@ -19,19 +19,51 @@ const HEADING = /^#{1,6}\s/
  * headings was the alternative and it clears no plan already written, leaving
  * each flagged until someone rewrites it.
  *
- * The marker starts at column zero and carries a colon, and the whole line is
- * the marker or none of it is. A bold phrase opening a sentence is emphasis
- * rather than a seam, and an indented one is a label inside a list item, so
- * both stay prose. This ships as package data every project reads, where a
- * missed break costs one unbroken run and a false one shortens every run around
- * it until the measure stops reporting, which is the dearer of the two.
- *
- * The colon is what a colon-less `**Testing**` is held out by, and that shape
- * is a real section marker in a review body rather than a hypothetical. Widening
- * to reach it moves the shipped pattern rather than the wording, so the rule
- * states the colon and the widening stays open for a decision of its own.
+ * The marker starts at column zero and the whole line is the marker or none of
+ * it is. A bold phrase opening a sentence is emphasis rather than a seam, and
+ * an indented one is a label inside a list item, so both stay prose. This ships
+ * as package data every project reads, where a missed break costs one unbroken
+ * run and a false one shortens every run around it until the measure stops
+ * reporting, which is the dearer of the two.
+ *
+ * A colon ends most markers and not all of them. `claude-pr-review` writes
+ * three colon-less ones into every body it posts and a bold path heading for
+ * each file it reviews, so requiring the colon held a real seam out. Two
+ * signals stand in where the colon is absent, because the shape a marker has to
+ * be told from is a sentence set in bold and no one test separates both kinds
+ * of marker from it.
+ *
+ * A label that is one whole code span breaks at any width. A path runs long and
+ * a sentence set in bold is never a single span, so shape settles this half
+ * where width cannot. Across 81 colon-less markers in the review bodies posted
+ * on this repository, the 30 path headings run from 20 to 70 characters, and no
+ * colon-less line in the records tree is a whole span at all, so the rule adds
+ * reach without adding a false break.
+ *
+ * `MARKER_WIDTH` covers the rest and is read off the corpus rather than picked.
+ * Of the remaining 51 markers in those review bodies, 50 sit at or under 20
+ * visible characters, and so do 48 of the 94 colon-less lines in the records
+ * tree at `9960a4d7`, every one of them a label. The 21 to 30 band above it
+ * holds 8 lines nobody can classify on sight, where `One change across four
+ * files.` reads as a sentence and `Rule plus a mechanical half` reads as a
+ * seam, so the ceiling sits under that band rather than over it. That is where
+ * the asymmetry above points, a false break being the dearer error. Terminal
+ * punctuation separates nothing, since 45 of the 48 shortest colon-less lines
+ * end in one.
+ *
+ * Both signals govern the colon-less shape alone. A colon is its own evidence
+ * of a label, and capping the colon form as well takes the break back from four
+ * markers between 31 and 50 characters that already have it, every one of them
+ * a genuine section marker.
+ *
+ * One marker in that review corpus is reached by neither signal, a 48-character
+ * heading a session wrote by hand rather than from the template. Widening to
+ * catch it means raising the ceiling back through the band, so it is left as
+ * the cheap error the asymmetry above already names.
  */
-const SECTION_MARKER = /^\*\*[^*]+:\*\*\s*$/
+const BOLD_LINE = /^\*\*([^*]+)\*\*\s*$/
+const SPAN_LABEL = /^`[^`]+`$/
+const MARKER_WIDTH = 20
 
 const LIST_ITEM = /^(\s*)([-*+]|\d+\.)\s+/
 const TABLE_ROW = /^\s*\|/
@@ -272,11 +304,33 @@ function isTableRun(run: readonly BodyLine[]): boolean {
   return separators > 0
 }
 
+/**
+ * Reports whether a line is a section marker rather than emphasis.
+ *
+ * `BOLD_LINE` fixes the shape, and a colon-less label then answers to
+ * `SPAN_LABEL` or to `MARKER_WIDTH`, per the record above. Both read visible
+ * text, which reduces a link to its anchor text and leaves a backticked path
+ * counted whole, the same reading `isScannablePeerList` takes. The reduction is
+ * what lets a linked path reach the span test at all, since the markup around
+ * it would fail the pattern the destination is still attached.
+ */
+function isSectionMarker(text: string): boolean {
+  const marker = text.match(BOLD_LINE)
+  if (!marker) return false
+
+  const label = marker[1]
+  if (label.endsWith(':')) return true
+
+  const visible = visibleText(label)
+
+  return SPAN_LABEL.test(visible) || visible.length <= MARKER_WIDTH
+}
+
 /**
  * Measures the longest run of lines no signpost breaks, in rendered lines.
  *
  * A heading breaks a run and so does a section marker, which is the same
- * signpost written the way a template asked for it. `SECTION_MARKER` above
+ * signpost written the way a template asked for it. `isSectionMarker` above
  * fixes which lines qualify.
  *
  * Fenced lines are skipped rather than treated as breaks, per the standard:
@@ -325,7 +379,7 @@ export function longestRun(
   for (const line of lines) {
     if (line.fenced) continue
 
-    if (HEADING.test(line.text) || SECTION_MARKER.test(line.text)) {
+    if (HEADING.test(line.text) || isSectionMarker(line.text)) {
       close()
       continue
     }

package/standards/markdown.md

@@ -37,7 +37,8 @@ Does not govern:
 - Exempt a block whose lines are all table rows, at any length. The peer list above is exempt because it is already navigable, and a table because the remedy does not exist: a subheading dropped inside one splits the table rather than the run, so no edit short of rewriting it as a list clears the checkpoint.
 - Prose either side of the table ends that exemption, since the block has a seam and a heading breaks it there.
 - Break a run on a bold section marker holding its line alone, the way a heading breaks one. A document whose template separates sections with `**Risks:**` rather than `## Risks` has written the seam a reader lands on, and reading only the heading reported every such file at its full length whatever it carried.
-- Require the marker to start at column zero and to end in a colon inside the bold, and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item. A colon-less `**Testing**` does not break either, which holds a real section marker out and is the cost of keeping the pattern narrow on data every project is measured against.
+- Require the marker to start at column zero and to be the whole line. `**Risks:**` breaks a run, a bold phrase opening a sentence stays emphasis, and an indented one stays a label inside its list item.
+- Break a colon-less marker on either of two signals, since no one test separates every marker from a sentence set in bold. A label that is one whole code span breaks at any width, which is how a bold line holding only a backticked path reads as the file heading it is. Anything else breaks at 20 characters or fewer, which reaches `**Testing**` and leaves a bold sentence as prose.
 
 ## Paragraphs and lists
 

package/standards/rule.md

@@ -32,14 +32,14 @@ Write both when both apply. A rule stating the directive and a skill stating how
 ## Location
 
 - Rules live at `.claude/rules/<subdirectory>/<n>-<slug>.md`
-- Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`
+- Subdirectories group by domain: `core/`, `lang/`, `framework/`, `lib/`, `ui/`, `claude/`, `snippets/`, `ci/`
 - `<n>` is a number from the band reserved for the rule's source and `<slug>` is a one-to-three-word kebab topic
 - A rule the project authored itself lives at `.claude/rules/project/<subdirectory>/<n>-<slug>.md`, keeping the same subdirectory names
 - Give every rule a numeric prefix. A bare-word filename reads as a folder name where a stack names its rules, so a rule without one is unreachable from a stack entry.
 
 ## Reserved numbers
 
-`000-899` is reserved for a rule set that ships to targets. `000-599` is what the six subdirectories above already divide, at 100 per subdirectory, and `600-899` is held for subdirectories a shipped set has not added yet.
+`000-899` is reserved for a rule set that ships to targets. `000-599` is what the first six subdirectories above already divide, at 100 per subdirectory. `ci/` was the first to draw from the headroom past that, taking `700-799`, and `600-699` with `800-899` is what remains for a subdirectory a shipped set has not added yet.
 
 A project-authored rule takes `900-999`, one sequence across every subdirectory under `.claude/rules/project/`. Scanning for a free number instead is what fails, because a shipped set fills its own band release by release, so what reads as free today is what a later release lands on. One target authored `claude/561-self-check.md` on a day nothing shipped at 561, met `claude/561-teach.md` on its next install, and now reads two numbers differently from everywhere else.