@erclx/aitk 0.12.0 → 0.13.0

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

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

package/claude/skills/bash-script/SKILL.md

@@ -35,7 +35,7 @@ Load `${CLAUDE_SKILL_DIR}/references/patterns.md` for the timeline lifecycle, lo
 - Name functions verb-first: `validate_input`, `deploy_service`, `install_dependencies`.
 - Do not use global variables except exports from `ask()`.
 - Do not define unused color variables.
-- Do not include comments except the shebang line.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
 - Use sentence case for section headers and log messages. Proper nouns and product names retain their casing.
 - Quote variables inside parameter expansions: `"${file#"$dir"/}"` not `"${file#$dir/}"`.
 - Quote variables in test brackets: `[ "$i" -eq "$cur" ]` not `[ $i -eq $cur ]`.

package/claude/skills/claude-review/SKILL.md

@@ -85,6 +85,8 @@ Flag only issues that will definitely cause incorrect behavior or break a docume
 - Linter territory
 - Issues that depend on unverified state
 
+A comment that makes a false claim about the code is a correctness finding, not a style one. Flag it past the exclusions above and let the severity ladder rank it.
+
 If uncertain, do not flag. False positives erode trust.
 
 ### Severity

package/claude/skills/cli-script/SKILL.md

@@ -33,7 +33,7 @@ Load `${CLAUDE_SKILL_DIR}/references/template.md` for the base skeleton. Copy it
 - Decompose by responsibility. Each function does one thing, `main()` orchestrates.
 - Name functions verb-first: `parse_args`, `fetch_data`, `validate_input`.
 - Quote variables in expansions and test brackets.
-- Do not include comments except the shebang line.
+- Comment only a fact the reader cannot recover from the code, and follow the code-comment rule in `.claude/rules/` when the project installs it.
 - Use 2-space indentation.
 
 ## Validation

package/docs/agents.md

@@ -204,14 +204,16 @@ aitk sandbox check claude:docs drift --json
 
 | Flag                | Effect                                                     |
 | ------------------- | ---------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, and denials from a run       |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
 | `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
 | `--json`            | Emit the verdict record on stdout                          |
 | `--strict`          | Exit 1 on `unchecked` instead of 0                         |
 
 The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
 
-Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope and the turn ceiling report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+
+An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 
 Exit 0 means `pass` or `unchecked`. Exit 1 means `fail`, or a caller error: a malformed target, or a sandbox that was never provisioned. A missing sandbox reports as an error rather than a failed verdict, because failing every path assertion would read as a skill that did nothing. `--strict` moves `unchecked` to exit 1 for a caller that has finished arming its scenarios.
 
@@ -323,6 +325,8 @@ Two exclusions are structural rather than tuning. Heredoc bodies are dropped fro
 
 The degradation sweep reads its vocabulary from whichever rule publishes a `## Degradation vocabulary` heading, preferring `.claude/rules/` over `governance/rules/`, so one definition serves the toolkit and every target. Discovery anchors on the heading rather than a filename, because a renumbered rule would otherwise empty the vocabulary while the sweep still reported clean. With no such rule the sweep reports **skipped** rather than zero hits, since finding nothing and looking for nothing mean opposite things.
 
+`090-code-comments` is the rule that publishes the list, and it ships on the `base` stack. A project that installs or syncs governance for the first time after that rule landed gets a sweep that previously reported skipped, so hits appear where the command used to stay quiet. Edit the backticked terms in the installed copy to change what that project sweeps for. The sweep matches comment text, so a comment naming a term as an example is a hit, and a hit is a prompt to read the line rather than a verdict on it.
+
 ## Runtime catalogs
 
 Use these to discover what's available instead of hardcoding names.

package/governance/rules/core/090-code-comments.md

@@ -0,0 +1,39 @@
+---
+description: Decide when a code comment should exist and what it may claim
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.js'
+  - '**/*.jsx'
+  - '**/*.sh'
+  - '**/*.py'
+---
+
+# Code comment standards
+
+## When a comment should exist
+
+- Write a comment only when it records a fact the reader cannot recover from the code: an external contract, a rejected alternative, or the reason a surprising line is correct.
+- Do not restate in prose what the line beside it already says.
+- Do not comment a self-contained function whose signature and body already carry its behavior.
+- Let comment density follow how much of a file's behavior is decided outside that file. Treat density as an outcome, never as a target.
+- Do not add or delete a comment to move a file toward a density figure.
+
+## What a comment may claim
+
+- State only what is true of the code as written.
+- Describe a function's contract and its constraints, never its steps line by line.
+- Update or delete an invalidated comment in the same change that invalidates it.
+- Do not name a person, a ticket, or a date in place of the fact itself.
+
+## What never goes in a comment
+
+- Delete commented-out code. Do not park it beside the live path.
+- Do not record the edit that produced the code. Version control holds the change history.
+- Do not defer work into a comment. Deferred work belongs in the tracker.
+
+## Degradation vocabulary
+
+Do not write a comment carrying any of these terms.
+
+- `FIXED`, `BUGFIX`, `HACK`, `XXX`, `NOTE:`, `TODO`, `FIXME`, `don't remove`, `previously`, `used to`, `workaround`

package/governance/stacks/base.toml

@@ -1,2 +1,2 @@
 extends = ""
-rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]
+rules = ["000-constitution", "010-testing", "020-concurrency", "030-error-handling", "040-performance", "050-logging", "060-naming", "070-planning", "080-config-comments", "090-code-comments", "500-prose", "510-context", "520-wireframes", "530-requirements", "540-architecture", "550-design", "555-tasks", "560-diagrams", "570-skill", "580-readme", "590-rule-authoring", "591-standard-authoring"]

package/package.json

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

package/scripts/lib/frontmatter.sh

@@ -4,7 +4,7 @@
 #
 # Kept in bash because the list commands call it once per field per file
 # inside a loop, where shelling into the CLI would cost a process per read.
-# The index engine that used to live here is TypeScript, in src/indexes/.
+# Index logic is TypeScript, in src/indexes/, and does not belong here.
 read_frontmatter_field() {
   local file="$1"
   local key="$2"

package/src/commands/sandbox.ts

@@ -86,6 +86,11 @@ async function interactivePicker(): Promise<string> {
  * file was given, so the turn ceiling reports as skipped rather than passing on a
  * fabricated zero. A file that exists but does not parse falls back to clean,
  * since decision 8 lets the envelope fail a run but never pass one.
+ *
+ * `result` carries the reply text and is left undefined on both fallbacks, which
+ * routes a reply assertion to skipped. Fabricating an empty string there would
+ * fail every reply assertion on a run that supplied no envelope, turning a gap in
+ * the input into a red arm.
  */
 function readEnvelope(path: string | undefined): RunEnvelope | undefined {
   if (path === undefined) return undefined
@@ -102,6 +107,7 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
       isError: parsed.is_error === true,
       turns: typeof parsed.num_turns === 'number' ? parsed.num_turns : 0,
       denials: Array.isArray(denials) ? denials.length : 0,
+      reply: typeof parsed.result === 'string' ? parsed.result : undefined,
     }
   } catch {
     return CLEAN_ENVELOPE

package/src/sandbox/expect.ts

@@ -19,6 +19,7 @@ export interface Expectation {
   readonly absent: readonly string[]
   readonly content: readonly ContentAssertion[]
   readonly writeScope: readonly string[]
+  readonly reply: readonly string[]
   readonly manual: readonly string[]
   readonly maxTurns?: number
 }
@@ -28,10 +29,17 @@ export interface AssertionResult {
   readonly message: string
 }
 
+/**
+ * `reply` is optional because an absent reply and an empty one mean different
+ * things. A run whose envelope was never supplied has nothing to assert against
+ * and skips. A run that genuinely returned no text carries the empty string and
+ * fails every reply assertion, which is the finding.
+ */
 export interface RunEnvelope {
   readonly isError: boolean
   readonly turns: number
   readonly denials: number
+  readonly reply?: string
 }
 
 export interface Verdict {
@@ -155,6 +163,7 @@ export function parseExpectation(source: string): Expectation {
     absent: stringArray(parsed.absent),
     content: contentArray(parsed.content),
     writeScope: stringArray(parsed.write_scope),
+    reply: stringArray(parsed.reply),
     manual: stringArray(parsed.manual),
     maxTurns:
       typeof parsed.max_turns === 'number' ? parsed.max_turns : undefined,
@@ -171,7 +180,8 @@ export function countMechanicalAssertions(expectation: Expectation): number {
     expectation.paths.length +
     expectation.absent.length +
     expectation.content.length +
-    expectation.writeScope.length
+    expectation.writeScope.length +
+    expectation.reply.length
   )
 }
 
@@ -259,6 +269,42 @@ function checkWriteScope(
   }
 }
 
+/**
+ * Plain substrings, matched case-sensitively, against the text the run replied
+ * with. A substring rather than a regex because the pattern a reply assertion
+ * wants is a load-bearing token, a path or a command, and a regex invites the
+ * anchored sentence that goes red on any rewording.
+ *
+ * Declare only positives. A negative substring passes on every reply that
+ * phrases the thing differently, which is the vacuous pass
+ * `countMechanicalAssertions` excludes `manual` to prevent. An entry asserting
+ * what a run must not have said stays in `manual` with its reason.
+ */
+function checkReply(
+  expectation: Expectation,
+  envelope: RunEnvelope | undefined,
+): KindOutcome {
+  if (expectation.reply.length === 0) return { results: [], skipped: [] }
+
+  if (envelope?.reply === undefined) {
+    return {
+      results: [],
+      skipped: ['reply: no reply text supplied, pass --envelope'],
+    }
+  }
+
+  const reply = envelope.reply
+
+  return {
+    results: expectation.reply.map((fragment) =>
+      reply.includes(fragment)
+        ? { ok: true, message: `reply says: ${fragment}` }
+        : { ok: false, message: `reply never says: ${fragment}` },
+    ),
+    skipped: [],
+  }
+}
+
 /**
  * The envelope never determines a pass. It can only fail a run the expectations
  * would otherwise have passed. Under `bypassPermissions` the denial count is
@@ -306,16 +352,18 @@ export function checkExpectation(
   input: CheckInput,
 ): Verdict {
   const scope = checkWriteScope(expectation, input.writes)
+  const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)
 
   const results = [
     ...checkPaths(expectation, input.sandboxDir),
     ...checkAbsent(expectation, input.sandboxDir),
     ...checkContent(expectation, input.sandboxDir),
+    ...reply.results,
     ...scope.results,
     ...envelope.results,
   ]
-  const skipped = [...scope.skipped, ...envelope.skipped]
+  const skipped = [...scope.skipped, ...reply.skipped, ...envelope.skipped]
 
   const failed = results.filter((result) => !result.ok).length
 

package/standards/architecture.md

@@ -17,7 +17,7 @@ Applies to `.claude/ARCHITECTURE.md`. Describes the system shape and the decisio
 
 - Per-domain structure and narrative. That belongs in `.claude/context/<domain>.md`, one file per domain.
 - Setup commands and install instructions. Those live in the README.
-- How individual functions work line by line. Those go in code comments.
+- How individual functions work line by line. The code carries its own behavior.
 - Full type definitions. They live in code. Reference the shape conceptually if needed.
 
 ## Sections