[so0k]

Related issue

None. Docs and agent-tooling only; no package code is touched.

Description

Adds a test-audit agent skill under .claude/skills/test-audit/. It has two everyday uses and one occasional one:

• Authoring gate: before a test is added, name the contract it protects, the regression that would fail it, the tier that should own it, why existing coverage misses it, and whether it needs a production seam no production caller needs.
• Audit: sweep existing tests for ones that duplicate stronger proof, assert implementation rather than behavior, cannot fail, or keep test-only seams alive.
• Campaign (CAMPAIGN.md): prune one package's or one owner area's whole test surface, one lane per PR.

Origin

The skill is adapted from the test-audit skill in openclaw/openclaw (MIT), taken at eb1b48c. VENDOR.md records this.

The value bar, junk patterns, candidate evidence and campaign steps are upstream's. What is specific to this repository replaces the openclaw parts (Vitest, plugins, their PR tooling):

• TIERS.md: the test tiers (static gates, unit, unit with the Terraform/OpenTofu matrix, integration, provider integration, examples), how CI routes each, what a green run does and does not prove, and the commands.
• A "which tier owns it?" question in the authoring gate, so a contract is proven once at the cheapest tier that can observe the failure.
• Snapshot rules, since much of the proof here is snapshots of synthesized JSON, HCL and generated bindings.
• A retention bar naming this repo's contracts (synth output, logical IDs and asset hashes, names kept across the cdktf rename, feature flags, generated bindings, the version matrix, language bindings, the shipped Testing API).

Doc alignment

• CLAUDE.md recommends the skill when adding or changing tests. It no longer points at a constitution path that is not in the repository (the principles are stated inline), and it lists the PR title types and scopes pr-lint.yml actually allows.
• CONTRIBUTING.md gains the perf, test and revert types, and a pnpm test:watch script that does not exist is replaced with the Nx watch command.

Findings from trialling it

The skill was run read-only over the diff of #473 (feat(lib): support a pluggable asset hash algorithm) as a first trial. The result is posted there as a non-blocking review. In short, of the seven tests that PR adds:

• four pass the gate;
• two are redundant: each asserts an inequality between a 64-character and a 32-character digest, which cannot fail while its sibling format test passes;
• one could be narrowed to the single assertion nothing else covers.

It also found production paths the diff changes with no test: the per-App hash cache key, OUTPUT hashing with a bundler, the new option on the legacy (flag-off) scheme, a literal pin for default hash values on either scheme, and a missing guard for an out-of-range algorithm.

The trial fed back into the skill before this PR: one statement that turned out to be wrong was removed, the commands were corrected and verified, and the tier and command reference was split out into TIERS.md to keep SKILL.md close to the upstream's size.

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have run the linter on my code locally (prettier --check on CLAUDE.md and CONTRIBUTING.md; .claude/ is prettier-ignored)
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas (not applicable)
• I have made corresponding changes to the documentation if applicable (not applicable)
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works if applicable (not applicable)
• New and existing unit tests pass locally with my changes (not run; no package code changed)

🤖 Generated with Claude Code

[sakul-learning]

Non-blocking content notes from comparing .claude/skills/test-audit with my test-review rubric:

• .claude/skills/test-audit/SKILL.md says never to run a blanket -u, while CLAUDE.md and CONTRIBUTING.md still recommend the repository-wide pnpm test:update / pnpm integration:update commands. Consider qualifying the rule: focused changes should update only the intended file; broad update commands are for deliberate migrations where every changed snapshot is reviewed.
• .claude/skills/test-audit/CAMPAIGN.md says to “keep the deletion” when main modifies a test file the campaign planned to remove. The following sentence does require porting its new contract, but wording this as “re-evaluate the incoming change, port all new coverage, then retain the deletion” would make the preservation requirement harder to skip.
• The “one owning tier” rule is useful, but “one primary owning tier” would better preserve legitimate additional tests for distinct packaging, binary, platform, language-binding, security, or failure-mode risks. The retention section already captures much of this nuance.

My rubric, very briefly: test observable behavior and credible regressions at the cheapest durable boundary; ensure tests run in normal validation; question skips, static scans, duplicate coverage, and test-only seams; require evidence and remaining keeper coverage before deleting anything.

[so0k]

Thanks, all three taken in 20543f6.

• Blanket -u: the Snapshots rule in SKILL.md now says to update only the snapshot file you meant to change, and that the repository-wide commands (pnpm test:update, pnpm integration:update) are for a deliberate migration where every changed entry is still reviewed. CLAUDE.md and CONTRIBUTING.md are unchanged.
• Campaign reconcile: CAMPAIGN.md step 8 now leads with re-evaluating the incoming change and porting every new contract and regression into the keeper, and only then keeps the deletion.
• Owning tier: reworded to "one primary owning tier", which matches authoring-gate question 4 ("another tier or language needs its own distinct risk").

[jsteinich]

Non-blocking review. I checked the skill's factual claims against the workflows and tooling; most hold (Nx tags, the pr-unit.yml matrix, the integration retry, the Testing.app future-flag default, the hcl2cdk CI gate, the test:update targets). Inline notes below on the ones that don't.

One more outside the diff: this PR aligns CLAUDE.md and CONTRIBUTING.md with pr-lint's allowed types, but subjectPatternError in .github/workflows/pr-lint.yml still says the supported types are only feat, fix, chore, refactor and revert. A contributor with a malformed title is told test and perf are unsupported. Worth fixing at the source alongside the docs.

🤖 Generated with Claude Code

[so0k]

Thanks for checking the claims against the workflows. All six inline notes are addressed in 80f134c, with a reply on each thread.

The note outside the diff is fixed in the same commit: subjectPatternError in pr-lint.yml now lists test and perf.

Two things the review surfaced are documented here but not fixed, since they are workflow changes and not docs:

• CI does not package before cdktn-cli's dist-gated init.test.ts unless @cdktn/hcl2cdk is affected, and never on main.
• @cdktn/hcl-tools is absent from the unit matrices in release.yml.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days. This helps our maintainers find and focus on the active issues. If you've found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.