@erclx/aitk 0.83.0 → 0.85.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.83.0",
+  "version": "0.85.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/git-pr/references/labels.md

@@ -40,7 +40,13 @@ The map is authored by hand and nothing detects a directory it fails to cover, s
 
 Apply labels after the pull request resolves, never as a flag on the create. `gh pr create --label` fails whole on a label the remote does not carry, so a name the map got wrong opens no pull request at all and the run stops with the branch pushed and nothing to review. A `gh pr edit --add-label` against a pull request that already exists costs a warning instead, and it is one command across both the create and the edit path rather than two flags that have to stay in step.
 
-`--add-label` adds and never removes. A label a person applied by hand is not this skill's to strip, so a domain that stops applying between two pushes keeps its label until someone takes it off.
+Labelling runs whenever this skill runs and at no other time. Nothing else computes the set, so a push made any other way leaves the labels exactly as the last run left them. Any caller invoking this skill again reaches the step again, and it recomputes over the whole branch diff rather than over the new commits.
+
+An ordinary branch therefore labels once, when the pull request opens. The return leg that answers a review hands its push to `git-followup`, which refreshes the body without invoking this skill, so the commits that answer a review reach no labelling step.
+
+A follow-up push reaching a surface the earlier ones did not merges under-labelled, with nothing to report the miss. Keeping the step in one skill is worth that cost, since a review fix lands in the files the review named and rarely opens a surface the branch had not already touched.
+
+`--add-label` adds and never removes. A label a person applied by hand is not this skill's to strip, and a re-run over a branch that has since dropped a surface keeps the label that surface earned.
 
 ## A label the remote does not carry
 

package/docs/agents/markdown-audit.md

@@ -116,7 +116,9 @@ Four surfaces read the ban sets and two of them go through this verb. `.claude/h
 
 The other two read the standards directly and neither is a consolidation left half done. `claude/skills/claude-standards-audit/SKILL.md` greps the banned tokens agent-side, which is a session reading prose rather than a process it can shell out to, and it ships to every target. The seed copy of the hook keeps its awk, because a scaffolded project may carry no `aitk` and `scripts/core/check-seed-independence.sh` exists to catch seed content depending on the toolkit CLI. Both are the likelier place for the next drift, since nothing compares either against the verb.
 
-The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. A machine with neither runner gets no enforcement at edit time rather than a blocked edit, and the push stage still holds.
+The hook prefers a checkout's own `src/cli.ts` over a globally installed binary, so it and the push stage read one build. A published binary lags a branch by whatever has not been released, which would put a ban kind added on the branch into the push and not into the edit. It reads its findings out of the `--json` record rather than off the exit code, so an older binary still reports where the fallback applies. It reads `bans.missingStandards` out of the same record, so a standard the verb found under neither root reaches the author as a check narrowed to what it could read.
+
+A machine with neither runner still blocks no edit, and it says so rather than exiting clean. The push stage holds either way. An edit nobody checked and an edit carrying no violation are one silence to a reader, so the enforcement a machine lacks is reported rather than inferred.
 
 The stage measures the whole corpus rather than the changed files. A `Do not use` bullet added to a standard bans a token retroactively, and no file in the push that adds the bullet was edited.
 

package/governance/rules/claude/520-wireframes.md

@@ -6,7 +6,15 @@ paths:
 
 # Wireframe standards
 
+## Layout and intent
+
+- Draw each surface as an ASCII block inside a `plaintext` fence, one fence per distinct layout.
+- Label a region with its role. Never label one with a class name, a token name, or a computed value.
+- Carry on-screen copy verbatim, and mark copy the surface templates.
+- State interaction intent, never the mechanism behind it. Send algorithms, handlers, and thresholds to a `.claude/context/` entry.
+- Update a surface's wireframe in the same pull request that changes its layout or its interaction.
+
 ## Authority
 
 - Follow `.claude/standards/wireframes.md` for layout and interaction intent: ASCII layout, region labels, variants, copy, and what moves to `.claude/context/`. It is the single source.
-- A wireframe carries layout and intent, not implementation. Read the standard before adding or revising a surface.
+- Read it before adding or revising a surface.

package/governance/rules/claude/530-requirements.md

@@ -6,6 +6,14 @@ paths:
 
 # Requirements standards
 
+## Scope and non-goals
+
+- State a goal as a user-facing outcome, never as the implementation delivering it.
+- Record explicit non-goals. Mark a deferred item `(deferred)`.
+- Leave the MVP list as written once its features ship. Do not renumber it, extend it, or annotate an entry with status.
+- Add later scope as a new section rather than as an extension of the MVP list.
+- Drop a section rather than pad it. Include `## Distribution` only when the project ships outside its own repository.
+
 ## Authority
 
 - Follow `.claude/standards/requirements.md` for what belongs in the problem, goals, non-goals, MVP features, tech stack, and constraints. It is the single source.

package/governance/rules/claude/540-architecture.md

@@ -6,6 +6,16 @@ paths:
 
 # Architecture standards
 
+## Decisions
+
+- Give each decision its own H3 under `## Key technical decisions`, naming what it chose and the alternative it passed over.
+- Keep line-by-line function behavior and full type definitions out.
+
+## Verification anchors
+
+- Close a decision citing a measured number with `Measured at <short-sha> on <YYYY-MM-DD>.` Leave a decision citing none unanchored.
+- Refresh that anchor whenever the number is re-read, whether or not it moved.
+
 ## Authority
 
 - Follow `.claude/standards/architecture.md` for the overview, named decision entries, and risks. It is the single source.

package/governance/rules/claude/550-design.md

@@ -6,6 +6,14 @@ paths:
 
 # Design standards
 
+## Tokens
+
+- Describe a token as intent rather than as a computed value.
+- Keep CSS classes, component filenames, and prop names out.
+- Carry a token system as a table, one row per token, and a component rule as a short bullet.
+- Keep the token table headers verbatim.
+- Record a non-obvious omission, such as no motion or no custom icons.
+
 ## Authority
 
 - Follow `.claude/standards/design.md` for visual intent, the token tables, and the render contract. It is the single source.

package/governance/rules/claude/555-tasks.md

@@ -6,6 +6,14 @@ paths:
 
 # Tasks standards
 
+## What a task carries
+
+- Name where the task came from, through a `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` line under the title.
+- Size the outcomes so one pull request closes all of them. Split the task before handing it off.
+- Use `## Outcomes` and `## Findings` and add no third heading. Note status inline on an outcome.
+- Keep class names, file paths, function names, and prop names out of every entry and title.
+- Never delete a task file. A shipped task moves to the archive under its own name.
+
 ## Authority
 
 - Follow `.claude/standards/tasks.md` for filenames, frontmatter, what belongs, and the task file format. It is the single source.

package/governance/rules/claude/580-readme.md

@@ -6,6 +6,14 @@ paths:
 
 # README standards
 
+## Audience and voice
+
+- Write a repository-root README for someone deciding whether to commit to the project. A nested README keeps the reference voice.
+- Address the reader in second person.
+- Ground a claim in a command, a number, or a named constraint rather than an adjective.
+- Name what the project does not do.
+- Link out to full API documentation, license text, contribution guidelines, and troubleshooting rather than carrying them.
+
 ## Authority
 
 - Follow `.claude/standards/readme.md` for voice, structure, required and optional sections, heading hierarchy, badge classes, per-project-type content, and what to link out rather than inline. It is the single source.

package/governance/rules/claude/590-rule-authoring.md

@@ -6,6 +6,17 @@ paths:
 
 # Rule authoring standards
 
+## Numbering
+
+- Name a rule `.claude/rules/<subdirectory>/<n>-<slug>.md`, taking a number that collides with neither the project's rules nor any installed shared set.
+- Give every rule a numeric prefix and keep the slug to one to three kebab words.
+
+## Body
+
+- State one directive per bullet in imperative voice. Do not explain the reasoning behind a rule.
+- Cut a rule that resists crisp one-line phrasing.
+- Do not restate a rule a sibling rule or `CLAUDE.md` already owns. Point once.
+
 ## Authority
 
 - Follow `.claude/standards/rule.md` for rule frontmatter, body shape, and voice. It is the single source.

package/governance/rules/claude/591-standard-authoring.md

@@ -7,6 +7,14 @@ paths:
 
 # Standard authoring standards
 
+## The scope statement
+
+- Govern one document type per standard, or one attribute across every document.
+- Open with a `## Scope` section naming what the standard governs and a `Does not govern:` list, placed above the shape rules.
+- Put the governed path in backticks in the first sentence, anchored deep enough to resolve from a project root. Keep an attribute standard's first sentence free of backticks and say in it that it governs an attribute.
+- Give each `Does not govern:` entry an excluded concern and the owner it goes to. Cut an entry naming no owner.
+- Declare a yield, an exemption, or a handoff from both sides of the boundary.
+
 ## Authority
 
 - Follow `.claude/standards/standard.md` for a standard's frontmatter, shape, scope, and success criterion. It is the single source.

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

@@ -12,4 +12,5 @@ description: Enforce planning standards before implementation
 - State where the search ran and why each candidate was rejected. Do not assert a search without naming its results.
 - Propose the simplest solution that satisfies the requirement before implementing complex patterns.
 - 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.
 - Do not modify code without a confirmed plan.

package/governance/rules/core/075-dependencies.md

@@ -0,0 +1,25 @@
+---
+description: Require a dependency to be declared in the manifest before it is imported
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.js'
+  - '**/*.jsx'
+  - '**/*.py'
+  - '**/package.json'
+  - '**/pyproject.toml'
+---
+
+# Dependency standards
+
+## Declaration
+
+- Declare a package in the project manifest before importing it anywhere in the source.
+- Add a package with the package manager command that writes the manifest and the lockfile together, such as `bun add` or `uv add`. Never hand-edit the manifest and never install without recording the result.
+- Commit the lockfile with the manifest change in the same commit.
+- Declare a package used only by tests, builds, or tooling as a development dependency.
+- Never import a package that arrives only as a transitive dependency of another package.
+
+## Removal
+
+- Remove a package from the manifest in the change that removes its last import.

package/governance/rules/lib/300-testing-ts.md

@@ -32,7 +32,7 @@ paths:
 ## Conventions
 
 - Use `.test.ts` / `.test.tsx` for unit tests.
-- Use `.spec.ts` / `.spec.tsx` for integration tests.
+- Use `.spec.ts` / `.spec.tsx` for integration tests and for Playwright tests under `e2e/`.
 - Do not make real network calls in unit tests.
 - `describe()` labels use the exact identifier of the subject under test in its natural casing.
 - `it()` descriptions use "should" + sentence case.

package/governance/rules/lib/360-security-server.md

@@ -0,0 +1,39 @@
+---
+description: Enforce server-side authorization, secret handling, and abuse limits on request handlers
+paths:
+  - '**/*.py'
+  - '**/*.ts'
+  - '**/*.js'
+---
+
+# Server security standards
+
+## Authorization
+
+- Authorize every request on the server, whatever the client already checked.
+- Derive the caller identity from the verified session or token. Never read it from a request body, query string, or header the client sets.
+- Check that the caller owns or may reach the specific record a request names, not only that the caller is signed in.
+- Deny by default. Grant a route access through an explicit allow.
+
+## Credentials
+
+- Hash passwords with a memory-hard algorithm and a per-record salt. Never store a reversible password.
+- Compare tokens, signatures, and password hashes with a constant-time function.
+- Expire and revoke sessions and refresh tokens on the server. Do not rely on client-side deletion.
+
+## Secrets
+
+- Read every secret from the environment or a secret manager at runtime.
+- Never commit a secret, connection string, or private key to the repository.
+- Never return a secret, connection string, or internal hostname in a response body.
+
+## Abuse limits
+
+- Rate-limit authentication, password reset, and any endpoint that sends mail or costs money per call.
+- Set an explicit maximum body size and request timeout on every endpoint.
+- Bound pagination parameters with a server-side maximum.
+
+## Transport
+
+- Serve every route over TLS and reject plaintext requests.
+- Restrict CORS to an explicit origin list. Never reflect the request origin or pair a wildcard with credentials.

package/governance/rules/lib/370-database.md

@@ -0,0 +1,35 @@
+---
+description: Enforce persistence boundaries for migrations, query construction, transactions, and rollback
+paths:
+  - '**/*.py'
+  - '**/*.ts'
+  - '**/*.js'
+  - '**/*.sql'
+---
+
+# Persistence standards
+
+## Schema changes
+
+- Express every schema change as a migration file committed to version control.
+- Ship a tested rollback path with every migration that changes a schema.
+- Never alter a deployed schema outside a migration.
+- Never edit a migration that has run in a shared environment. Add a new one.
+- Separate a destructive migration from the deploy that stops reading the dropped column.
+
+## Query construction
+
+- Pass every runtime value as a bound parameter.
+- Never interpolate, concatenate, or format a value into a statement string.
+- Name the columns a read needs. Do not select every column by wildcard.
+
+## Transactions
+
+- Give each transaction one owner that opens it, commits it, and rolls it back.
+- Never open a transaction inside a function that was handed one.
+- Keep network calls, queue publishes, and filesystem writes outside an open transaction.
+
+## Access patterns
+
+- Load related rows in the query that fetches their parents. Do not resolve a relation lazily inside an iteration.
+- Scope a connection or session to the request that opened it and release it on exit.

package/governance/stacks/python.toml

@@ -1,2 +1,2 @@
 extends = "base"
-rules = ["110-python", "340-pydantic", "330-testing-py"]
+rules = ["110-python", "340-pydantic", "330-testing-py", "360-security-server", "370-database"]

package/package.json

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

package/tooling/claude/seeds/.claude/hooks/standards-audit.sh

@@ -33,6 +33,7 @@ esac
 # bullet added to markdown.md is parsed by nothing and enforces silently.
 standard="${CLAUDE_PROJECT_DIR:-.}/.claude/standards/prose.md"
 words=""
+unread=""
 if [ -f "$standard" ]; then
   words=$(grep '^- Do not use ' "$standard" |
     grep -o '`[^`]*`' |
@@ -40,6 +41,12 @@ if [ -f "$standard" ]; then
     grep -x '[a-z][a-z]*' |
     sort -u |
     paste -sd '|' -)
+else
+  # An absent standard empties the word list, and the awk below reads an empty
+  # list as nothing to look for rather than as nothing found. The path is kept
+  # so the report names what could not be read, since a file carrying no banned
+  # word and a file nobody checked produce the same silence otherwise.
+  unread="$standard"
 fi
 
 hits=$(awk -v words="$words" '
@@ -66,8 +73,18 @@ hits=$(awk -v words="$words" '
   }
 ' "$file")
 
-[ -z "$hits" ] && exit 0
+[ -z "$hits" ] && [ -z "$unread" ] && exit 0
 
-msg=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
+nl=$'\n'
+msg=""
+
+if [ -n "$unread" ]; then
+  msg=$(printf 'Standards-audit: no word ban checked in %s. Found no standard at %s, so only the character bans ran. Restore it with `aitk standards install`.' "$file" "$unread")
+fi
+
+if [ -n "$hits" ]; then
+  found=$(printf 'Standards-audit: prose.md and markdown.md violations in %s. Rewrite or restructure (do not lazy-swap).\n%s' "$file" "$hits")
+  msg="${msg:+$msg$nl}$found"
+fi
 
 jq -nc --arg msg "$msg" '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$msg}}'