@1aboveio/skills 1.0.3 → 1.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/package.json +2 -2
  2. package/skills/app-dev/airflow/SKILL.md +1 -1
  3. package/skills/app-dev/android-foundation/SKILL.md +1 -1
  4. package/skills/app-dev/app-debug/SKILL.md +1 -1
  5. package/skills/app-dev/better-auth/SKILL.md +1 -1
  6. package/skills/app-dev/data-catalog/SKILL.md +1 -1
  7. package/skills/app-dev/data-quality/SKILL.md +1 -1
  8. package/skills/app-dev/ios-foundation/SKILL.md +1 -1
  9. package/skills/app-dev/monorepo/SKILL.md +1 -1
  10. package/skills/app-dev/nextjs-fullstack/SKILL.md +1 -1
  11. package/skills/app-dev/prisma-setup/SKILL.md +1 -1
  12. package/skills/app-dev/pyspark/SKILL.md +54 -12
  13. package/skills/app-dev/pyspark/references/adaptive-batching.md +294 -0
  14. package/skills/app-dev/pyspark/references/diagnosis-and-profiling.md +24 -3
  15. package/skills/app-dev/pyspark/references/etl-contract.md +27 -0
  16. package/skills/app-dev/pyspark/references/production-validation.md +41 -11
  17. package/skills/app-dev/pyspark/references/reconciliation.md +28 -3
  18. package/skills/app-dev/pyspark/references/transformation-design.md +20 -0
  19. package/skills/app-dev/python-backend/SKILL.md +1 -1
  20. package/skills/app-dev/shadcn/SKILL.md +1 -1
  21. package/skills/app-dev/zod-v4/SKILL.md +1 -1
  22. package/skills/cicd/cloud-build/SKILL.md +1 -1
  23. package/skills/cicd/cloud-debug/SKILL.md +1 -1
  24. package/skills/cicd/cloud-deploy/SKILL.md +1 -1
  25. package/skills/cicd/docker/SKILL.md +1 -1
  26. package/skills/cicd/github-actions/SKILL.md +1 -1
  27. package/skills/cicd/github-flow/SKILL.md +1 -1
  28. package/skills/cicd/google-cloud/SKILL.md +1 -1
  29. package/skills/cicd/mergify/SKILL.md +1 -1
  30. package/skills/cicd/podman/SKILL.md +1 -1
  31. package/skills/content/article-review/SKILL.md +1 -1
  32. package/skills/content/article-to-image/SKILL.md +1 -1
  33. package/skills/content/flowchart-svg/SKILL.md +1 -1
  34. package/skills/content/image-gen/SKILL.md +1 -1
  35. package/skills/content/mermaid/SKILL.md +1 -1
  36. package/skills/content/wechat-article-writer/SKILL.md +1 -1
  37. package/skills/content/wechat-publisher/SKILL.md +1 -1
  38. package/skills/content/wechat-search/SKILL.md +1 -1
  39. package/skills/content/xai-search/SKILL.md +1 -1
  40. package/skills/core/distill-writing/SKILL.md +1 -1
  41. package/skills/core/doc-to-md/SKILL.md +1 -1
  42. package/skills/core/editorial-review/SKILL.md +1 -1
  43. package/skills/core/house-style/SKILL.md +1 -1
  44. package/skills/core/house-style/references/defaults.md +32 -6
  45. package/skills/core/plain-language/SKILL.md +87 -4
  46. package/skills/core/polish-cn/SKILL.md +1 -1
  47. package/skills/core/reg-parser/SKILL.md +1 -1
  48. package/skills/core/terminology/SKILL.md +1 -1
  49. package/skills/core/write-doc/SKILL.md +1 -1
  50. package/skills/engineering/better-review/SKILL.md +1 -1
  51. package/skills/engineering/contributing/SKILL.md +1 -1
  52. package/skills/engineering/e2e-test/SKILL.md +1 -1
  53. package/skills/engineering/engineering-runtime/SKILL.md +1 -1
  54. package/skills/engineering/engineering-runtime/coherence/workflow.json +13 -13
  55. package/skills/engineering/ensure-coverage/SKILL.md +1 -1
  56. package/skills/engineering/golden-path/SKILL.md +1 -1
  57. package/skills/engineering/harness-runtime/SKILL.md +1 -1
  58. package/skills/engineering/resolve-issues/SKILL.md +1 -1
  59. package/skills/engineering/resolve-release/SKILL.md +1 -1
  60. package/skills/engineering/rush-issues/SKILL.md +1 -1
  61. package/skills/engineering/rush-release/SKILL.md +1 -1
  62. package/skills/engineering/test-quality/SKILL.md +4 -4
  63. package/skills/engineering/test-quality/references/audit.md +1 -0
  64. package/skills/engineering/test-quality/references/principles.md +4 -2
  65. package/skills/engineering/test-quality/references/testing-conventions.md +1 -1
  66. package/skills/risk-compliance/compliance-audit/SKILL.md +1 -1
  67. package/skills/risk-compliance/contract-compare/SKILL.md +1 -1
  68. package/skills/risk-compliance/contract-review/SKILL.md +1 -1
  69. package/skills/risk-compliance/doc-authenticity/SKILL.md +1 -1
  70. package/skills/risk-compliance/fraud-analysis/SKILL.md +1 -1
  71. package/skills/risk-compliance/payment-analysis/SKILL.md +1 -1
  72. package/skills/risk-compliance/report-writing/SKILL.md +1 -1
  73. package/skills/risk-compliance/similar-domain/SKILL.md +1 -1
  74. package/skills/risk-compliance/tld-detection/SKILL.md +1 -1
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: write-doc
3
3
  description: "Write or edit a Markdown document in the project's house style, using the nearest WRITING.md and a document template (BRD, PRD, gap analysis, technical spec, integration guide, commercial proposal, compliance policy, risk operations procedure, or the project's own); English, Chinese or bilingual. NOT for learning a style from samples (distill-writing), audit reports from findings (report-writing), or WeChat articles (wechat-article-writer)."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Write a document
@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/better-review). Single-agent adversarial rev
4
4
  disable-model-invocation: true
5
5
  dependencies:
6
6
  - engineering-runtime
7
- release-version: 0.40.0
7
+ release-version: 0.42.0
8
8
  ---
9
9
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
10
10
  # Better Review
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: contributing
3
3
  description: "The conventions a repo's CONTRIBUTING.md holds, starting with tracker routing: which tracker an issue belongs in (GitHub for engineering, Linear for product), duplicate search, and linking back to the source requirement. Use before creating any issue, spec, epic, ticket or sub-issue on GitHub or Linear, including inside /to-spec, /to-tickets and /triage, and whenever work that started from a Linear issue turns into engineering work. Also writes the rules as the Issue tracking section of the repo's CONTRIBUTING.md. NOT for delivering a PR (github-flow) or splitting work into slices (to-tickets)."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Contributing
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: e2e-test
3
3
  description: "Playwright end-to-end standard: the 3-tier suite (render-health / functional / journey), generated route manifest, and presentation sweep. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), the curated ALIVE/DEAD golden-path gate (golden-path), or CI workflow YAML (github-actions)."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # E2E Testing Standard
@@ -3,7 +3,7 @@ name: engineering-runtime
3
3
  description: Internal support package for shared Engineering Workflow executable behavior. Never select or invoke this package as a user capability.
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.40.0
6
+ release-version: 0.42.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Engineering Runtime
@@ -369,7 +369,7 @@
369
369
  "repository": "1aboveio/ai",
370
370
  "revision": "main"
371
371
  },
372
- "contentDigest": "cce3cfb21f16ea64b5b008ef9970b1cdf4cf2b1410f32105e3b305821acf1c1f",
372
+ "contentDigest": "29dda87aaa4090bbc1b8ac3f3eaa66261cdea76c88f9eac034eb8c85ad767431",
373
373
  "digestExcludes": []
374
374
  },
375
375
  {
@@ -382,7 +382,7 @@
382
382
  "repository": "1aboveio/ai",
383
383
  "revision": "main"
384
384
  },
385
- "contentDigest": "c87e5250fe86e4e01f5bf8d4db59f77893de385bba4fc34742429147b22b5253",
385
+ "contentDigest": "5cbfd6c6efe831db62de5dfaf6a969a57fb948da18d1f15343a4f9fb929b5d1f",
386
386
  "digestExcludes": []
387
387
  },
388
388
  {
@@ -395,7 +395,7 @@
395
395
  "repository": "1aboveio/ai",
396
396
  "revision": "main"
397
397
  },
398
- "contentDigest": "5e449cef39b924bddd4b24cf64ea63b5b93e745194100d797ddd830bd00a97b7",
398
+ "contentDigest": "a6beb9f98cf5bd1b0b93dfaf9d7370b442661996fd17ace25db4ead102e656f6",
399
399
  "digestExcludes": []
400
400
  },
401
401
  {
@@ -408,7 +408,7 @@
408
408
  "repository": "1aboveio/ai",
409
409
  "revision": "main"
410
410
  },
411
- "contentDigest": "35b0a26911041468eda83f0b3829f343806d39292a381984de39fef2f813ec4b",
411
+ "contentDigest": "61cbdbdae25549a16147280204cbb2e539d19a9ebda12e18544c5ba441de8104",
412
412
  "digestExcludes": []
413
413
  },
414
414
  {
@@ -421,7 +421,7 @@
421
421
  "repository": "1aboveio/ai",
422
422
  "revision": "main"
423
423
  },
424
- "contentDigest": "b9e265715330e802d711d0a47012bc32c91d882656e227530f51b08976672d20",
424
+ "contentDigest": "2ad0540e1e0591fc2979a8f319d5ce6741aa7a8ab1d6f913b177b40d1d325a33",
425
425
  "digestExcludes": []
426
426
  },
427
427
  {
@@ -434,7 +434,7 @@
434
434
  "repository": "1aboveio/ai",
435
435
  "revision": "main"
436
436
  },
437
- "contentDigest": "6b4736a329dcf2d35eeb74ea019aaa39b82fb129fbd735e55d68c3bab063d046",
437
+ "contentDigest": "30da0eabbec9040a1ed9b51553b4bed54e69ec4f288904dc2536be330f7e625a",
438
438
  "digestExcludes": []
439
439
  },
440
440
  {
@@ -447,7 +447,7 @@
447
447
  "repository": "1aboveio/ai",
448
448
  "revision": "main"
449
449
  },
450
- "contentDigest": "d2645ec3b2b28cc08cd4026d6ffb7e56d43e31031c024004b79a07a5fc59bb25",
450
+ "contentDigest": "9b9f791716e53350d538e52649835888f7329f64f0f09df741eeaf4180214f9a",
451
451
  "digestExcludes": []
452
452
  },
453
453
  {
@@ -460,7 +460,7 @@
460
460
  "repository": "1aboveio/ai",
461
461
  "revision": "main"
462
462
  },
463
- "contentDigest": "61708f1a0dd9024f7cc1c99661c074cee6299587220f22ce197d2ec312a79370",
463
+ "contentDigest": "3f645b737fbfd24f558bb84c5c4690abf76f19292a3382614ef2369333d9c4e4",
464
464
  "digestExcludes": []
465
465
  },
466
466
  {
@@ -473,7 +473,7 @@
473
473
  "repository": "1aboveio/ai",
474
474
  "revision": "main"
475
475
  },
476
- "contentDigest": "ece6ce482174817c58344af70149085a594df54b8e70e8535ec267e26f5e00ab",
476
+ "contentDigest": "8c7e031f4193dee85aa3c372dbde007bc4eda3c3be8a01782af1eae22eae3597",
477
477
  "digestExcludes": []
478
478
  },
479
479
  {
@@ -486,7 +486,7 @@
486
486
  "repository": "1aboveio/ai",
487
487
  "revision": "main"
488
488
  },
489
- "contentDigest": "ddaf8300548bcf2628fa6b6f6933885e05dc0451f5ca0e9bb6629fcca2c673bb",
489
+ "contentDigest": "c7ee7f4efa548aefce16d471f33e821baf297eb457b05c971c13eac7b242a56f",
490
490
  "digestExcludes": []
491
491
  },
492
492
  {
@@ -499,7 +499,7 @@
499
499
  "repository": "1aboveio/ai",
500
500
  "revision": "main"
501
501
  },
502
- "contentDigest": "00c5971a8363fc1382afa6914707e764c9d3d0cb76a8e3a3ffcfd1d9d5fd5da5",
502
+ "contentDigest": "ee9cbd827623de79d82049ce3d591df928459d5366f0acf2d58c278e22d0f8a4",
503
503
  "digestExcludes": []
504
504
  },
505
505
  {
@@ -512,13 +512,13 @@
512
512
  "repository": "1aboveio/ai",
513
513
  "revision": "main"
514
514
  },
515
- "contentDigest": "1599a61cc8f82eec8dd1b426604ec55ba65c503e4c793c5e57670e737e765462",
515
+ "contentDigest": "5913c86a3e73d20b4bf9ef3f1426fbbe41295226bc6e2d6ef9bf08e1e7a9fb36",
516
516
  "digestExcludes": [
517
517
  "coherence/workflow.json"
518
518
  ]
519
519
  }
520
520
  ],
521
- "releaseIdentity": "5d71cce8b6dec3bb1fe3ad66fa046bdc870d197d110685d2d8981410c56f5686",
521
+ "releaseIdentity": "39b7ac8ecbc245defbeeb73a7d4c2e872a32c3bc992b95590058cd236952efc1",
522
522
  "lifecycleAuthority": "native-skills-cli",
523
523
  "repairRecipe": {
524
524
  "id": "engineering-workflow-dependency-first",
@@ -2,7 +2,7 @@
2
2
  name: ensure-coverage
3
3
  description: "Define or audit behavior-first test criteria — ACs, required test levels, mock/integration/E2E policy — across three axes: breadth (Coverage Ledger), depth (over-mocking), presentation (perceivability of browser surfaces). NOT judging whether a single test is any good (test-quality), authoring browser tests (e2e-test), reviewing a PR (better-review), or delivering issues (resolve-issues)."
4
4
  disable-model-invocation: true
5
- release-version: 0.40.0
5
+ release-version: 0.42.0
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # Ensure Coverage
@@ -3,7 +3,7 @@ name: golden-path
3
3
  description: "Golden-path E2E: the short list of user journeys whose failure blocks a release, kept in a repo as one contract (golden-paths.json) with a generated GOLDEN_PATHS.md and a generated GitHub Actions workflow, and run against a local build or a deployed URL for an ALIVE/DEAD verdict. Use to set golden paths up in a repo ('init golden paths', 'add golden-path CI'), to migrate an older smoke.manifest.json or a hand-built smoke setup ('audit', 'migrate smoke'), to add, change, or remove a golden path, to ask 'is the build alive?' or run them before a PR or release, or when a change touches a flow listed in GOLDEN_PATHS.md. NOT for writing the Playwright specs themselves (e2e-test), deciding what a change must prove (ensure-coverage), or general workflow YAML (github-actions)."
4
4
  dependencies:
5
5
  - e2e-test
6
- release-version: 0.40.0
6
+ release-version: 0.42.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Golden path
@@ -3,7 +3,7 @@ name: harness-runtime
3
3
  description: Internal import-only library shared by first-party engineering packages. Not a workflow skill; never select or invoke it as a user capability.
4
4
  disable-model-invocation: true
5
5
  user-invocable: false
6
- release-version: 0.40.0
6
+ release-version: 0.42.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Harness Runtime
@@ -8,7 +8,7 @@ dependencies:
8
8
  - better-review
9
9
  - golden-path
10
10
  - harness-runtime
11
- release-version: 0.40.0
11
+ release-version: 0.42.0
12
12
  ---
13
13
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
14
14
  # Resolve issues
@@ -4,7 +4,7 @@ description: "Slash/explicit-only (/resolve-release). Full GitHub Flow release f
4
4
  disable-model-invocation: true
5
5
  metadata:
6
6
  workflow-role: coordinator
7
- release-version: 0.40.0
7
+ release-version: 0.42.0
8
8
  ---
9
9
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
10
10
  # Resolve release
@@ -6,7 +6,7 @@ metadata:
6
6
  workflow-role: coordinator
7
7
  dependencies:
8
8
  - resolve-issues
9
- release-version: 0.40.0
9
+ release-version: 0.42.0
10
10
  ---
11
11
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
12
12
  # Rush issues (shortcut of resolve-issues)
@@ -6,7 +6,7 @@ metadata:
6
6
  workflow-role: coordinator
7
7
  dependencies:
8
8
  - resolve-release
9
- release-version: 0.40.0
9
+ release-version: 0.42.0
10
10
  ---
11
11
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
12
12
  # Rush release (shortcut of resolve-release)
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: test-quality
3
3
  description: "Seven principles for tests that catch real bugs, and an audit that reports weak, redundant, and not-coverage tests without fixing them. Use when writing, changing, or reviewing tests, or when asked whether tests are useful, redundant, over-mocked, flaky, only assert static text, or test config files, or asked to make a slow test suite faster without losing coverage, or when the user asks to write the testing conventions into a repo's CONTRIBUTING.md. NOT defining what a spec must prove (ensure-coverage) or authoring browser tests (e2e-test)."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Test Quality
@@ -20,7 +20,7 @@ A test is worth keeping when it fails for a real bug and stays green through a h
20
20
  | 4 | [An assertion must be able to fail](references/principles.md#4-an-assertion-must-be-able-to-fail) | Checks weaker than the test's name | no assertion, `NoError` only, bare `toThrow()`, a skip that always fires |
21
21
  | 5 | [Test each behavior once, and only for code that still runs](references/principles.md#5-test-each-behavior-once-and-only-for-code-that-still-runs) | Duplicates and dead weight | identical files; mocked unit twin of a real integration test |
22
22
  | 6 | [Don't test config files](references/principles.md#6-dont-test-config-files) | Restating a config file in a test | a Dockerfile, workflow, `cloudbuild.yaml`, `.mergify.yml`, `package.json`, or other JSON/YAML/TOML config read, then any assertion |
23
- | 7 | [Same code, same result](references/principles.md#7-same-code-same-result) | A result that depends on luck | `Math.random`/`uuid()`/`Date.now()` in checked output; `sleep(…)`; passes in the suite, fails alone |
23
+ | 7 | [Same code, same result](references/principles.md#7-same-code-same-result) | A result that depends on luck | `Math.random`/`uuid()`/`Date.now()` in checked output; `sleep(…)`; passes in the suite, fails alone; scratch files under the repo or `cwd` |
24
24
 
25
25
  ## The one question
26
26
 
@@ -39,11 +39,11 @@ A good assertion has a concrete answer to (1) and none to (2). An assertion with
39
39
  4. **An assertion must be able to fail.** Every test can go red and checks what its name promises: read the name's verbs ("atomically", "then", "corrected to") and find the assertion for each.
40
40
  5. **Test each behavior once, and only for code that still runs.** Prove each behavior once, at the lowest level that proves it for real. Layering (a pure unit for the decision table plus one real-DB test per rule) is not duplication; many similar cases merge into a table rather than being deleted.
41
41
  6. **Don't test config files.** Dockerfiles, `cloudbuild.yaml`, `.github/workflows/*`, `.mergify.yml`, `package.json`, `tsconfig.json`, `pyproject.toml`, `.env`, and any other JSON, YAML, or TOML a tool reads get no tests: the tool that reads the file is the test. Test the code that reads config; run scripts, because scripts are code. A pin added after a real bug is still a config test: delete it and name the missing behavior check as a follow-up. JSON the app loads as data (locales, price tables) is not config.
42
- 7. **Same code, same result.** Anything that changes between runs (randomness, the clock, timing, run order, the network) is fixed by the test: seed it, freeze it, wait on the condition, own your state.
42
+ 7. **Same code, same result.** Anything that changes between runs (randomness, the clock, timing, run order, the network, where files land) is fixed by the test: seed it, freeze it, wait on the condition, own your state and your files (a fresh temp directory per test, removed afterwards).
43
43
 
44
44
  ## Audit mode
45
45
 
46
- Reviewer subagents audit and never fix. The **quick audit** is the default and finishes in under 10 minutes: `lint-tests.mjs --shares 4` splits the flagged files, at most 4 reviewers (or the harness's parallel limit) read only their flagged spots on a 6-minute budget, each writes its report to a file and replies in one line, and the lead merges once and posts once, with no per-reviewer updates. A **deep audit** (every test file read) runs only when the user asks for one. Any request that ends in changed tests ("audit and fix", "clean up the tests", "improve the suite") then runs **fix** (implementer subagents, disjoint files; each opens a `Redundant` test's twin and searches for what depends on a test before deleting it) → **verify** (lint on the diff, fresh reviewer on the fix). A request to make the suite faster without losing coverage measures durations first and collapses slow files by code path ([speed](references/audit.md#when-the-goal-is-speed)). Steps, budgets, and the report template: [references/audit.md](references/audit.md).
46
+ Reviewer subagents audit and never fix. The **quick audit** is the default and finishes in under 10 minutes: `lint-tests.mjs --shares 4` splits the flagged files, at most 4 reviewers (or the harness's parallel limit) read only their flagged spots on a 6-minute budget, each writes its report to a file and replies in one line, and the lead merges once and posts once, with no per-reviewer updates. A **deep audit** (every test file read) runs only when the user asks for one. Any request that ends in changed tests ("audit and fix", "clean up the tests", "improve the suite") then runs **fix** (implementer subagents, disjoint files; each opens a `Redundant` test's twin and searches for what depends on a test before deleting it) → **verify** (lint on the diff, fresh reviewer on the fix). A request to make the suite faster without losing coverage measures durations first, removes overhead every test pays, then collapses slow files by code path ([speed](references/audit.md#when-the-goal-is-speed)). Steps, budgets, and the report template: [references/audit.md](references/audit.md).
47
47
 
48
48
  ### Labels
49
49
 
@@ -47,6 +47,7 @@ A request to make a suite faster "without losing coverage" is a fix request with
47
47
 
48
48
  - **Budget, unless the repo sets its own.** Measured on the CI runner, test execution only (checkout, install, database start and migrations excluded): the unit and integration lanes together take **3 minutes or less**, and the integration lane alone **under 2 minutes**. Neither lane drives a real browser; browser journeys belong to the E2E lane, which has its own budget of **5 minutes or less**. Over budget is a finding even when every test is sound.
49
49
  - **Measure before cutting.** Get per-file and per-test durations from the runner (Vitest's JSON reporter or a small reporter over `TestModule.diagnostic()`, `pytest --durations=0`, `go test -json`). For CI, measure on the CI runner: a laptop is often faster and less CPU-bound, so local timings mislead.
50
+ - **Find per-test overhead before cutting tests.** Durations say which files are slow, not why. Trace what the slow tests start and wait on (child processes, containers, database setup, network, file system) and count it per test. A cost every test pays, such as a subprocess each write triggers or setup repeated per test instead of per file, usually outweighs every duplicate in the suite. Remove that cost first, then prove the behavior it guarded still has a test that fails without it.
50
51
  - **Expect little from deleting fast tests.** Mocked unit tests run in milliseconds; removing duplicates is worth it for refactor noise, rarely for time. A few slow files usually dominate. Look in them for real-time waits ([principle 7](principles.md#7-same-code-same-result)) and combinatorial matrices.
51
52
  - **Collapse a matrix by code path, then prove it.** Map each case to the production branch it exercises (which lock, which recheck, which input class). Keep one case per distinct path and drop cases that differ only in data that takes the same path. Prove each kept case by disabling its path in production code, watching that case fail, and restoring the code. End with no production diff.
52
53
  - **Shorten a wait only when it stays deterministic.** Prefer faking the clock. When real elapsed time is the behavior, follow principle 7's look-alike for it instead of trimming the margin.
@@ -126,18 +126,20 @@ An over-mocked test is `Not coverage` **for the behavior the fake hides** (a moc
126
126
 
127
127
  ## 7. Same code, same result
128
128
 
129
- **Principle.** A test must pass or fail the same way on every run of the same code. Anything that changes between runs (randomness, the clock, timing, run order, the network) is fixed by the test, not left to chance.
129
+ **Principle.** A test must pass or fail the same way on every run of the same code. Anything that changes between runs (randomness, the clock, timing, run order, the network, where files land) is fixed by the test, not left to chance.
130
130
 
131
131
  **Done right.**
132
132
  - All IDs and random numbers come from one seeded generator or fixed ID factory; the seed is logged when randomness must stay.
133
133
  - The clock is frozen or injected; the time zone and locale are set by the test.
134
134
  - Async work is awaited on the condition it produces, not on a sleep.
135
135
  - Each test creates the state it needs and doesn't read what another test left.
136
+ - Each test writes its files to its own fresh temp directory (`tmp_path`, `t.TempDir()`, `mkdtemp(tmpdir())`) and removes it afterwards, including when the test fails or is killed.
136
137
 
137
138
  **Common failures.**
138
139
  - *Unseeded randomness:* random values in checked output now and then match a pattern check (a card-number scanner, a snapshot). Fixing values one at a time never ends; fix the source.
139
140
  - *Live clock:* passes all day, fails at midnight, at month end, or in another time zone.
140
141
  - *Fixed sleep:* `sleep(500)` before asserting async work. Passes on a fast machine, fails under load, and hides the condition the test should wait on.
141
142
  - *Order dependence:* passes in the full suite, fails when run alone, or the reverse.
143
+ - *Location dependence:* files written into the working tree or a shared path. The result or the run time changes with where the test runs (inside a Git checkout, on a shared CI workspace), and leftovers break the next run.
142
144
 
143
- **Not a failure.** A property-based or fuzz test that uses randomness on purpose and logs its seed, so any failure can be replayed. Real elapsed time that *is* the behavior, such as a deadline that must pass while a database lock is held, measured by the database clock that a fake cannot move. Wait on the condition (the clock passing the deadline), not a fixed sleep; treat an attempt whose precondition was observed too late as inconclusive and retry it with a longer margin; and assert persisted state afterwards, so a retried attempt cannot hide a bug.
145
+ **Not a failure.** A property-based or fuzz test that uses randomness on purpose and logs its seed, so any failure can be replayed. Real elapsed time that *is* the behavior, such as a deadline that must pass while a database lock is held, measured by the database clock that a fake cannot move. Wait on the condition (the clock passing the deadline), not a fixed sleep; treat an attempt whose precondition was observed too late as inconclusive and retry it with a longer margin; and assert persisted state afterwards, so a retried attempt cannot hide a bug. A test whose behavior *is* the working tree (a Git check, a file watcher) builds its own fixture repo or directory inside its temp directory instead of using the checkout it runs from.
@@ -6,4 +6,4 @@
6
6
  4. Make every assertion able to fail, and assert everything the test name promises.
7
7
  5. Test each behavior once, at the lowest level that proves it; delete tests of dead code.
8
8
  6. Don't test config files (Dockerfiles, CI workflows, `cloudbuild.yaml`, merge-queue config, `package.json`, other JSON/YAML/TOML a tool reads); test the code that reads them.
9
- 7. Seed randomness, freeze the clock, wait on conditions instead of sleeps, and never depend on another test's state.
9
+ 7. Seed randomness, freeze the clock, wait on conditions instead of sleeps, and never depend on another test's state; write files only to the test's own temp directory and remove it afterwards.
@@ -2,7 +2,7 @@
2
2
  name: compliance-audit
3
3
  version: 2.9.0
4
4
  description: "Audit operations against financial-compliance checklists (AML/KYC, VARS, PCI-DSS, TPA oversight, onboarding, transaction monitoring). Produces tracker.md (with a tracker.xlsx export) and phase-trail.md with layered validation; cites evidence by original filename. Input: reg-parser or the built-in VARS checklist."
5
- release-version: 0.40.0
5
+ release-version: 0.42.0
6
6
  ---
7
7
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
8
8
  # Compliance Audit
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: contract-compare
3
3
  description: "Compare two or more contracts side-by-side for structured diff, gap analysis, and benchmarking. Use when: comparing contracts or agreements, contract diff, compare terms, vendor-vs-vendor, compare our template vs theirs, compliance gap between contracts. NOT for single-contract risk review — use contract-review for that."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Contract Compare
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: contract-review
3
3
  description: "Review contracts for legal, commercial, and compliance risks via convert → chunk review → merge → validate (+ optional mandate preprocessing). Use for reviewing, auditing, or checking any contract, agreement, NDA, MSA, or SLA; input a file path (PDF/DOCX/TXT) or pasted text."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Contract Review
@@ -3,7 +3,7 @@ name: doc-authenticity
3
3
  version: 0.4.1
4
4
  description: "Screen PDF documents and raster images for fabrication, tampering, Photoshop or other image-editor use, and content validity. Detects file type, runs format-specific authenticity forensics, classifies bank statements, conversation logs, invoices, agreements, and other documents, then applies type-specific validity checks. Produces separate authenticity (NO_EVIDENCE_OF_MODIFICATION / SUSPICIOUS / LIKELY_MODIFIED / INCONCLUSIVE) and validity (VALID / INVALID / INCONCLUSIVE) verdicts. Use whenever a user asks whether a document, screenshot, scan, statement, invoice, contract, chat log, receipt, or payment evidence is genuine, original, edited, Photoshopped, manipulated, fake, or valid."
5
5
  disable-model-invocation: true
6
- release-version: 0.40.0
6
+ release-version: 0.42.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Document and Image Authenticity
@@ -10,7 +10,7 @@ description: >
10
10
  impact, and a business report. Use for fraud, scam, mule, account-takeover,
11
11
  chargeback, dispute, transfer, collection, or payout risk analysis even when the
12
12
  user does not name this skill.
13
- release-version: 0.40.0
13
+ release-version: 0.42.0
14
14
  ---
15
15
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
16
16
  # Fraud Analysis
@@ -14,7 +14,7 @@ description: >
14
14
  transactions" — even if they do not say payment-analysis. Do NOT use for
15
15
  supervised fraud-rule mining (fraud-analysis) or TLD / MCC-miscoding
16
16
  clusters (tld-detection).
17
- release-version: 0.40.0
17
+ release-version: 0.42.0
18
18
  ---
19
19
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
20
20
  # Payment Analysis
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: report-writing
3
3
  description: "Convert compliance audit findings into audience-formatted reports. Four styles: VARS Review Report (Visa's official 2025 template, required verbatim for VARS engagements), Audit Report (compliance team), External Assessment (regulators/external auditors), Management Report (board/C-suite). Use whenever audit output needs to become a deliverable, even just 'write up the findings'."
4
- release-version: 0.40.0
4
+ release-version: 0.42.0
5
5
  ---
6
6
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
7
  # Report Writing
@@ -8,7 +8,7 @@ description: >
8
8
  links, an entity chain, and a watchlist for the operator's next domains.
9
9
  Not transaction data (tld-detection) or fraud rules (fraud-analysis).
10
10
  disable-model-invocation: true
11
- release-version: 0.40.0
11
+ release-version: 0.42.0
12
12
  ---
13
13
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
14
14
  # Similar Domain
@@ -11,7 +11,7 @@ description: >
11
11
  with a ≤3-sentence summary.
12
12
  Not payment-analysis, fraud-analysis, or website research (similar-domain).
13
13
  disable-model-invocation: true
14
- release-version: 0.40.0
14
+ release-version: 0.42.0
15
15
  ---
16
16
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
17
17
  # TLD Detection