@1aboveio/engineering-skills 0.1.2 → 0.1.4

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.
package/README.md CHANGED
@@ -13,6 +13,7 @@ pi install npm:@1aboveio/engineering-skills
13
13
  ## Skills
14
14
 
15
15
  - `better-review`
16
+ - `contributing`
16
17
  - `e2e-test`
17
18
  - `engineering-runtime`
18
19
  - `ensure-coverage`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@1aboveio/engineering-skills",
3
- "version": "0.1.2",
3
+ "version": "0.1.4",
4
4
  "description": "Issue-to-PR and release orchestrators, review, coverage, golden paths and test quality.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -27,7 +27,7 @@
27
27
  "id": "engineering",
28
28
  "core": "@1aboveio/core-skills",
29
29
  "coreSkills": [],
30
- "digest": "ee393c80cf9c0578e71de64432c7e49613448c0758ac67b03067561d446676bc"
30
+ "digest": "5ae0c2314221ed22e21179b55e830701a0db65c7e5889289742d1c8b151358fb"
31
31
  },
32
32
  "publishConfig": {
33
33
  "registry": "https://registry.npmjs.org/",
@@ -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.39.0
7
+ release-version: 0.41.0
8
8
  ---
9
9
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
10
10
  # Better Review
@@ -0,0 +1,3 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 1AboveIO
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: contributing
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.41.0
5
+ ---
6
+ **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
7
+ # Contributing
8
+
9
+ Rules every engineering skill follows, whatever skill or harness is running, kept as sections of the
10
+ repo's `CONTRIBUTING.md`. Each rule is the authority; another skill's "publish to the configured
11
+ tracker" means the tracker these rules pick.
12
+
13
+ ## First use in a repo
14
+
15
+ Scripts live under **this skill's directory**: set `SKILL_DIR` to the directory you read this file
16
+ from, never your CWD. On the first trigger in a repo, write the `## Issue tracking` section into its
17
+ `CONTRIBUTING.md`, creating the file when it is missing:
18
+
19
+ ```sh
20
+ node "$SKILL_DIR/scripts/persist-conventions.mjs" --repo-root <repo-root> --if-missing --write \
21
+ [--linear-project "<Linear project>"]... [--github-repo <owner/name>]
22
+ ```
23
+
24
+ - **Pass every Linear project whose resources link to this repo.** Example: the `Checkout Risk`
25
+ project lists `https://github.com/acme/widgets`, so pass `--linear-project "Checkout Risk"`.
26
+ - **Pass `--github-repo` only when `origin` is not the GitHub repo.** Example: exit 2 with
27
+ `no GitHub origin remote` means pass it.
28
+ - **`--if-missing` never touches an existing section.** To rewrite it, run without `--if-missing`.
29
+ - **`AGENTS.md` indexes `CONTRIBUTING.md`.** The script adds a `## Contributing` pointer unless
30
+ `AGENTS.md` already names `CONTRIBUTING.md`, creates a missing `AGENTS.md`, and creates a missing
31
+ `CLAUDE.md` as a symlink to `AGENTS.md`, even when the section already exists.
32
+ - Report each file's result line; commit with the change you are making, or leave it for the user
33
+ when you make no other change.
34
+
35
+ ## Tracker routing
36
+
37
+ | Work item | Tracker |
38
+ |---|---|
39
+ | Product goals, business requirements, priorities, milestones | Linear |
40
+ | Consulting engagements, reports, research deliverables | Linear |
41
+ | Engineering specs and implementation epics | GitHub |
42
+ | Implementation tickets, technical investigations, refactors, engineering bugs | GitHub |
43
+ | Delivery progress for stakeholders | A summary in Linear that links to GitHub |
44
+
45
+ Before you create an issue:
46
+
47
+ 1. **Classify the work; the tracker follows the work, not where the request came from.** Example:
48
+ `/to-spec` run on a conversation about DEV-123 publishes a GitHub issue.
49
+ 2. **Resolve the GitHub repo in this order: the repo's `CONTRIBUTING.md` Issue tracking section, the
50
+ GitHub links in the source Linear project's resources, then ask the user. Never fall back to
51
+ Linear.** Example: a project linking two repos gets the repo the work changes; a project linking
52
+ none gets a question, not a Linear ticket.
53
+ 3. **Search before you create.** Example: `gh issue list --repo <owner/name> --state all --search
54
+ "<keywords>"`; reuse or comment on a match.
55
+ 4. **A Linear issue is a source reference, never a parent for implementation tickets.** Example: put
56
+ `Source: <Linear URL>` in the GitHub epic body and file the tickets as GitHub sub-issues of the
57
+ epic.
58
+ 5. **Link back once per epic.** Example: add the GitHub epic URL to the Linear requirement as a
59
+ link; never copy the GitHub tickets into Linear.
60
+ 6. **Report progress in Linear as a summary; acceptance stays with the requester.** Example: when the
61
+ last sub-issue closes, comment `Engineering complete: <epic URL>` on the Linear requirement and
62
+ leave its status alone.
63
+ 7. **An explicit destination from the user wins.** Example: "file this in Linear" files it in Linear.
64
+
65
+ ## Common wrong answers
66
+
67
+ - "The request came from Linear, so the tickets go in Linear." The work type decides, rule 1.
68
+ - "No tracker is configured, so use the one the conversation used." Resolve the repo, rule 2.
69
+ - "Mirror the epic into Linear so stakeholders see it." Post a summary with a link, rule 5.
70
+ - "All sub-issues closed, so the Linear requirement is done." Engineering complete is not accepted, rule 6.
@@ -0,0 +1,18 @@
1
+ ## Issue tracking
2
+
3
+ Engineering work for this repo is tracked in GitHub issues on `{{githubRepo}}`. Product work is tracked in Linear{{linearProjects}}.
4
+
5
+ | Work item | Tracker |
6
+ |---|---|
7
+ | Product goals, business requirements, priorities, milestones | Linear |
8
+ | Consulting engagements, reports, research deliverables | Linear |
9
+ | Engineering specs and implementation epics | GitHub |
10
+ | Implementation tickets, technical investigations, refactors, engineering bugs | GitHub |
11
+ | Delivery progress for stakeholders | A summary in Linear that links to GitHub |
12
+
13
+ 1. **Classify the work before you create an issue; the tracker follows the work, not where the request came from.** Example: a spec written from a Linear requirement is a GitHub issue on `{{githubRepo}}`.
14
+ 2. **A Linear issue is a source reference, never a parent for implementation tickets.** Example: put `Source: https://linear.app/<team>/issue/DEV-123` in the GitHub epic body and make the tickets GitHub sub-issues of that epic; do not create DEV-124 under DEV-123.
15
+ 3. **Search GitHub before you create an issue.** Example: `gh issue list --repo {{githubRepo}} --state all --search "<keywords>"`; reuse or comment on a match instead of filing a duplicate.
16
+ 4. **Link back to Linear once per epic, not once per ticket.** Example: add the GitHub epic URL to the Linear requirement as a link; do not copy the GitHub tickets into Linear.
17
+ 5. **Report engineering progress in Linear as a summary; acceptance stays with the requester.** Example: when the last sub-issue closes, comment "Engineering complete: <epic URL>" on the Linear requirement and leave its status for the requester to move.
18
+ 6. **An explicit destination from the user wins.** Example: "file this in Linear" files it in Linear.
@@ -0,0 +1,93 @@
1
+ #!/usr/bin/env node
2
+ import { spawnSync } from 'node:child_process';
3
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
4
+ import { homedir } from 'node:os';
5
+ import { dirname, join } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ const DAY_MS = 24 * 60 * 60 * 1000;
9
+ const WEEK_MS = 7 * DAY_MS;
10
+ const here = dirname(fileURLToPath(import.meta.url));
11
+
12
+ function readJson(path, fallback = {}) {
13
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
14
+ }
15
+
16
+ function frontmatterValue(text, key) {
17
+ const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
18
+ const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
19
+ return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
20
+ }
21
+
22
+ function repositoryOf(source) {
23
+ const value = String(source ?? '').trim();
24
+ const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
25
+ return match?.[1] ?? null;
26
+ }
27
+
28
+ function stableVersion(value) {
29
+ const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
30
+ return match ? match.slice(1).map(Number) : null;
31
+ }
32
+
33
+ function newer(left, right) {
34
+ for (let index = 0; index < 3; index += 1) {
35
+ if (left[index] !== right[index]) return left[index] > right[index];
36
+ }
37
+ return false;
38
+ }
39
+
40
+ function writeCache(path, value) {
41
+ try {
42
+ mkdirSync(dirname(path), { recursive: true });
43
+ writeFileSync(path, JSON.stringify(value));
44
+ } catch { /* A read-only cache must not block skill use. */ }
45
+ }
46
+
47
+ function main(now = Date.now()) {
48
+ if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
49
+ const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
50
+ const name = frontmatterValue(skill, 'name');
51
+ const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
52
+ if (!name || !localVersion) return;
53
+
54
+ const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
55
+ const entry = lock.skills?.[name];
56
+ const repository = repositoryOf(entry?.sourceUrl || entry?.source);
57
+ if (!repository) return;
58
+
59
+ const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
60
+ const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
61
+ const all = readJson(cachePath);
62
+ const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
63
+
64
+ if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
65
+ const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
66
+ encoding: 'utf8',
67
+ stdio: ['ignore', 'pipe', 'ignore'],
68
+ timeout: 1500,
69
+ });
70
+ cache.lastCheck = now;
71
+ if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
72
+ else delete cache.latestTag;
73
+ all[repository] = cache;
74
+ writeCache(cachePath, all);
75
+ }
76
+
77
+ const latestVersion = stableVersion(cache.latestTag);
78
+ if (!latestVersion || !newer(latestVersion, localVersion)) return;
79
+ if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
80
+
81
+ cache.notifiedTag = cache.latestTag;
82
+ cache.notifiedAt = now;
83
+ all[repository] = cache;
84
+ writeCache(cachePath, all);
85
+ const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
86
+ process.stdout.write(
87
+ `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
88
+ + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
89
+ + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
90
+ );
91
+ }
92
+
93
+ try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
@@ -0,0 +1,118 @@
1
+ // persist-conventions-core — write one skill's section into a repo's
2
+ // CONTRIBUTING.md, point AGENTS.md at the file, and make CLAUDE.md a symlink to
3
+ // AGENTS.md (Claude Code reads CLAUDE.md, not AGENTS.md). Import-only: each skill's
4
+ // `persist-conventions.mjs` is the always-running CLI wrapper that names its
5
+ // section, so no main-module guard here.
6
+ //
7
+ // Byte-identical copies live in test-quality (Testing conventions), github-flow
8
+ // (CI conventions, Delivery), data-catalog (Data catalog conventions) and
9
+ // contributing (Issue tracking);
10
+ // skills/conventions-sections.test.mjs keeps them identical and proves the sections
11
+ // coexist in one file.
12
+ //
13
+ // A section sits between `conventions:<id>` markers, so a re-run replaces only
14
+ // that block and keeps everything else, including other skills' sections.
15
+ // Nothing is written without --write: the user triggers the write, not an agent.
16
+
17
+ import fs from 'node:fs'
18
+ import path from 'node:path'
19
+
20
+ export const CONTRIBUTING_FILE = 'CONTRIBUTING.md'
21
+ const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
22
+
23
+ export const AGENTS_SECTION = [
24
+ '## Contributing',
25
+ '',
26
+ `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code, or creating issues: tests, CI, data definitions, issue tracking, and what to do after each commit.`,
27
+ '',
28
+ ].join('\n')
29
+
30
+ export function markers(id) {
31
+ return [`<!-- conventions:${id}:start -->`, `<!-- conventions:${id}:end -->`]
32
+ }
33
+
34
+ export function sectionBlock({ id, owner, body }) {
35
+ const [start, end] = markers(id)
36
+ const note = `<!-- Written by the ${owner} skill: re-run its persist-conventions.mjs --write to update; edit outside these markers. -->`
37
+ return `${start}\n${note}\n\n${body.trim()}\n${end}\n`
38
+ }
39
+
40
+ // Pure: the new CONTRIBUTING.md text given the current one (or null).
41
+ export function renderConventions(current, id, block) {
42
+ if (current == null) return `# Contributing\n\n${block}`
43
+ const [start, end] = markers(id)
44
+ const from = current.indexOf(start)
45
+ const to = current.indexOf(end)
46
+ if (from !== -1 && to > from) {
47
+ const after = current.slice(to + end.length).replace(/^\r?\n/, '')
48
+ return current.slice(0, from) + block + after
49
+ }
50
+ return `${current.replace(/\s*$/, '')}\n\n${block}`
51
+ }
52
+
53
+ // Pure: the new AGENTS.md text given the current one (or null).
54
+ export function renderAgents(current) {
55
+ if (current == null) return `# AGENTS.md\n\n${AGENTS_SECTION}`
56
+ if (MENTIONS_CONTRIBUTING.test(current)) return current
57
+ return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
58
+ }
59
+
60
+ // A missing CLAUDE.md becomes a symlink to AGENTS.md.
61
+ export const LINK_TO_AGENTS = Symbol('link CLAUDE.md to AGENTS.md')
62
+
63
+ // Pure: the new CLAUDE.md text given the current one (or null). A missing file
64
+ // becomes LINK_TO_AGENTS; a regular file keeps its content and gains the pointer
65
+ // unless it already names AGENTS.md or CONTRIBUTING.md.
66
+ export function renderClaude(current) {
67
+ if (current == null) return LINK_TO_AGENTS
68
+ if (/(?:^|[^\w-])(?:AGENTS|CONTRIBUTING)\.md/.test(current)) return current
69
+ return `${current.replace(/\s*$/, '')}\n\n${AGENTS_SECTION}`
70
+ }
71
+
72
+ export function persist(repoRoot, section, { write = false } = {}) {
73
+ const block = sectionBlock(section)
74
+ const plan = [
75
+ [CONTRIBUTING_FILE, (text) => renderConventions(text, section.id, block)],
76
+ ['AGENTS.md', renderAgents],
77
+ ['CLAUDE.md', renderClaude],
78
+ ]
79
+ return plan.map(([name, render]) => {
80
+ const file = path.join(repoRoot, name)
81
+ if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) return { file: name, action: 'unchanged' }
82
+ const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
83
+ const next = render(current)
84
+ const action = current == null ? 'create' : next === current ? 'unchanged' : 'update'
85
+ if (next === LINK_TO_AGENTS) {
86
+ if (write) fs.symlinkSync('AGENTS.md', file)
87
+ return { file: name, action: 'link' }
88
+ }
89
+ if (write && action !== 'unchanged') fs.writeFileSync(file, next)
90
+ return { file: name, action }
91
+ })
92
+ }
93
+
94
+ // `section` = { id, owner, title, body }. Exit 0 on success, 2 on a usage error.
95
+ export function runCli(argv, section, { cwd = process.cwd(), log = console.log } = {}) {
96
+ let repoRoot = cwd
97
+ let write = false
98
+ for (let i = 0; i < argv.length; i++) {
99
+ if (argv[i] === '--write') write = true
100
+ else if (argv[i] === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(cwd, argv[++i])
101
+ else {
102
+ log(`persist-conventions: unknown argument ${argv[i]}`)
103
+ return 2
104
+ }
105
+ }
106
+ if (!fs.statSync(repoRoot, { throwIfNoEntry: false })?.isDirectory()) {
107
+ log(`persist-conventions: not a directory: ${repoRoot}`)
108
+ return 2
109
+ }
110
+ const results = persist(repoRoot, section, { write })
111
+ const done = { create: 'created', link: 'linked to AGENTS.md', update: 'updated', unchanged: 'unchanged' }
112
+ for (const r of results) log(` ${r.file}: ${write || r.action === 'unchanged' ? done[r.action] : `would ${r.action}`}`)
113
+ const changed = results.filter((r) => r.action !== 'unchanged').length
114
+ log(write
115
+ ? `persist-conventions: ${section.title}: ${changed} file(s) written, ${results.length - changed} unchanged`
116
+ : `persist-conventions: ${section.title}: preview only, ${changed} file(s) would change; re-run with --write to write`)
117
+ return 0
118
+ }
@@ -0,0 +1,84 @@
1
+ // persist-conventions — the tracker routing rules as the `## Issue tracking`
2
+ // section of a repo's CONTRIBUTING.md (../SKILL.md, First use in a repo).
3
+ // Previews unless --write; --if-missing leaves an existing section alone.
4
+ //
5
+ // node persist-conventions.mjs [--repo-root <dir>] [--github-repo <owner/name>]
6
+ // [--linear-project <name>]... [--if-missing] [--write]
7
+ //
8
+ // The GitHub repo defaults to the `origin` remote of --repo-root.
9
+ import fs from 'node:fs'
10
+ import path from 'node:path'
11
+ import { spawnSync } from 'node:child_process'
12
+ import { fileURLToPath } from 'node:url'
13
+ import { CONTRIBUTING_FILE, LINK_TO_AGENTS, markers, renderAgents, renderClaude, runCli } from './persist-conventions-core.mjs'
14
+
15
+ const ID = 'tracker'
16
+ const TEMPLATE = fs.readFileSync(fileURLToPath(new URL('../references/tracker-conventions.md', import.meta.url)), 'utf8')
17
+
18
+ function githubRepoFromRemote(url) {
19
+ const m = /github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/.exec(url.trim())
20
+ return m ? m[1] : null
21
+ }
22
+
23
+ function renderBody(githubRepo, linearProjects) {
24
+ const linear = linearProjects.length
25
+ ? ` (projects: ${linearProjects.join(', ')})`
26
+ : ''
27
+ return TEMPLATE.replaceAll('{{githubRepo}}', githubRepo).replaceAll('{{linearProjects}}', linear)
28
+ }
29
+
30
+ // The section stays as it is; only a missing AGENTS.md index or CLAUDE.md link is added.
31
+ function indexOnly(repoRoot, write, log) {
32
+ let changed = 0
33
+ for (const [name, render] of [['AGENTS.md', renderAgents], ['CLAUDE.md', renderClaude]]) {
34
+ const file = path.join(repoRoot, name)
35
+ if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) continue
36
+ const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null
37
+ const next = render(current)
38
+ if (next === current) continue
39
+ changed++
40
+ log(` ${name}: ${write ? 'written' : 'would change'}`)
41
+ if (!write) continue
42
+ if (next === LINK_TO_AGENTS) fs.symlinkSync('AGENTS.md', file)
43
+ else fs.writeFileSync(file, next)
44
+ }
45
+ return changed ? `${changed} index file(s) ${write ? 'written' : 'would change'}` : 'nothing written'
46
+ }
47
+
48
+ function main(argv, { log = console.log } = {}) {
49
+ const rest = []
50
+ const linearProjects = []
51
+ let githubRepo = null
52
+ let ifMissing = false
53
+ let repoRoot = process.cwd()
54
+ for (let i = 0; i < argv.length; i++) {
55
+ const arg = argv[i]
56
+ if (arg === '--linear-project' && argv[i + 1]) linearProjects.push(argv[++i])
57
+ else if (arg === '--github-repo' && argv[i + 1]) githubRepo = argv[++i]
58
+ else if (arg === '--if-missing') ifMissing = true
59
+ else {
60
+ if (arg === '--repo-root' && argv[i + 1]) repoRoot = path.resolve(argv[i + 1])
61
+ rest.push(arg)
62
+ }
63
+ }
64
+ if (!githubRepo) {
65
+ const remote = spawnSync('git', ['-C', repoRoot, 'remote', 'get-url', 'origin'], { encoding: 'utf8' })
66
+ githubRepo = remote.status === 0 ? githubRepoFromRemote(remote.stdout) : null
67
+ }
68
+ if (!githubRepo) {
69
+ log('persist-conventions: no GitHub origin remote; pass --github-repo <owner/name>')
70
+ return 2
71
+ }
72
+ if (ifMissing) {
73
+ const file = path.join(repoRoot, CONTRIBUTING_FILE)
74
+ const current = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
75
+ if (current.includes(markers(ID)[0])) {
76
+ log(`persist-conventions: Issue tracking: section already present; ${indexOnly(repoRoot, argv.includes('--write'), log)}`)
77
+ return 0
78
+ }
79
+ }
80
+ const section = { id: ID, owner: 'contributing', title: 'Issue tracking', body: renderBody(githubRepo, linearProjects) }
81
+ return runCli(rest, section, { log })
82
+ }
83
+
84
+ process.exitCode = main(process.argv.slice(2))
@@ -0,0 +1,118 @@
1
+ // Tests for persist-conventions: the real CLI against real files in a temp repo.
2
+ import { test } from 'node:test'
3
+ import assert from 'node:assert/strict'
4
+ import { spawnSync } from 'node:child_process'
5
+ import { lstatSync, mkdtempSync, readFileSync, readlinkSync, rmSync, writeFileSync } from 'node:fs'
6
+ import { tmpdir } from 'node:os'
7
+ import { join } from 'node:path'
8
+ import { fileURLToPath } from 'node:url'
9
+
10
+ import { markers } from './persist-conventions-core.mjs'
11
+
12
+ const CLI = fileURLToPath(new URL('./persist-conventions.mjs', import.meta.url))
13
+ const [START, END] = markers('tracker')
14
+
15
+ function withRepo(fn, remote) {
16
+ const dir = mkdtempSync(join(tmpdir(), 'contributing-'))
17
+ try {
18
+ if (remote) {
19
+ spawnSync('git', ['init', '-q', dir])
20
+ spawnSync('git', ['-C', dir, 'remote', 'add', 'origin', remote])
21
+ }
22
+ return fn(dir, (name) => readFileSync(join(dir, name), 'utf8'))
23
+ } finally {
24
+ rmSync(dir, { recursive: true, force: true })
25
+ }
26
+ }
27
+
28
+ function run(dir, ...args) {
29
+ const res = spawnSync(process.execPath, [CLI, '--repo-root', dir, ...args], { encoding: 'utf8' })
30
+ return { code: res.status, out: res.stdout }
31
+ }
32
+
33
+ test('--write creates CONTRIBUTING.md with the section, the repo from origin, and the Linear projects', () => {
34
+ withRepo((dir, read) => {
35
+ const { code } = run(dir, '--linear-project', 'Checkout Risk', '--write')
36
+ assert.equal(code, 0)
37
+ const text = read('CONTRIBUTING.md')
38
+ assert.ok(text.startsWith('# Contributing\n'))
39
+ assert.ok(text.includes(START) && text.includes(END))
40
+ assert.match(text, /GitHub issues on `acme\/widgets`/)
41
+ assert.match(text, /Linear \(projects: Checkout Risk\)/)
42
+ assert.match(text, /gh issue list --repo acme\/widgets/)
43
+ assert.doesNotMatch(text, /\{\{/)
44
+ }, 'git@github.com:acme/widgets.git')
45
+ })
46
+
47
+ test('an https remote and an explicit --github-repo both name the repo', () => {
48
+ withRepo((dir, read) => {
49
+ assert.equal(run(dir, '--write').code, 0)
50
+ assert.match(read('CONTRIBUTING.md'), /GitHub issues on `acme\/widgets`\. Product work is tracked in Linear\./)
51
+ }, 'https://github.com/acme/widgets')
52
+ withRepo((dir, read) => {
53
+ assert.equal(run(dir, '--github-repo', 'acme/other', '--write').code, 0)
54
+ assert.match(read('CONTRIBUTING.md'), /`acme\/other`/)
55
+ })
56
+ })
57
+
58
+ test('without a GitHub remote or --github-repo it refuses with exit 2 and writes nothing', () => {
59
+ withRepo((dir) => {
60
+ const { code, out } = run(dir, '--write')
61
+ assert.equal(code, 2)
62
+ assert.match(out, /--github-repo/)
63
+ assert.throws(() => readFileSync(join(dir, 'CONTRIBUTING.md')))
64
+ })
65
+ })
66
+
67
+ test('--if-missing appends to an existing CONTRIBUTING.md once, then leaves the section alone', () => {
68
+ withRepo((dir, read) => {
69
+ writeFileSync(join(dir, 'CONTRIBUTING.md'), '# Contributing\n\nRun the tests.\n')
70
+ assert.equal(run(dir, '--if-missing', '--write').code, 0)
71
+ const first = read('CONTRIBUTING.md')
72
+ assert.ok(first.startsWith('# Contributing\n\nRun the tests.\n'))
73
+ assert.ok(first.includes(START))
74
+
75
+ const edited = first.replace('acme/widgets`. Product', 'acme/widgets`. Hand-edited. Product')
76
+ writeFileSync(join(dir, 'CONTRIBUTING.md'), edited)
77
+ const { code, out } = run(dir, '--if-missing', '--linear-project', 'Other', '--write')
78
+ assert.equal(code, 0)
79
+ assert.match(out, /already present/)
80
+ assert.equal(read('CONTRIBUTING.md'), edited)
81
+ }, 'git@github.com:acme/widgets.git')
82
+ })
83
+
84
+ test('without --write it previews and writes nothing', () => {
85
+ withRepo((dir) => {
86
+ const { code, out } = run(dir)
87
+ assert.equal(code, 0)
88
+ assert.match(out, /CONTRIBUTING\.md: would create/)
89
+ assert.throws(() => readFileSync(join(dir, 'CONTRIBUTING.md')))
90
+ }, 'git@github.com:acme/widgets.git')
91
+ })
92
+
93
+ test('the first run indexes CONTRIBUTING.md from AGENTS.md and links CLAUDE.md, once', () => {
94
+ withRepo((dir, read) => {
95
+ assert.equal(run(dir, '--if-missing', '--write').code, 0)
96
+ assert.match(read('AGENTS.md'), /\[CONTRIBUTING\.md\]\(CONTRIBUTING\.md\).*issue tracking/)
97
+ assert.ok(lstatSync(join(dir, 'CLAUDE.md')).isSymbolicLink())
98
+ assert.equal(readlinkSync(join(dir, 'CLAUDE.md')), 'AGENTS.md')
99
+ }, 'git@github.com:acme/widgets.git')
100
+ withRepo((dir, read) => {
101
+ writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n\nSee CONTRIBUTING.md for everything.\n')
102
+ assert.equal(run(dir, '--if-missing', '--write').code, 0)
103
+ assert.equal(read('AGENTS.md'), '# Agents\n\nSee CONTRIBUTING.md for everything.\n')
104
+ }, 'git@github.com:acme/widgets.git')
105
+ })
106
+
107
+ test('--if-missing restores a missing AGENTS.md index even when the section is already present', () => {
108
+ withRepo((dir, read) => {
109
+ assert.equal(run(dir, '--write').code, 0)
110
+ const section = read('CONTRIBUTING.md')
111
+ writeFileSync(join(dir, 'AGENTS.md'), '# Agents\n')
112
+ const { code, out } = run(dir, '--if-missing', '--write')
113
+ assert.equal(code, 0)
114
+ assert.match(out, /already present; 1 index file\(s\) written/)
115
+ assert.match(read('AGENTS.md'), /^# Agents\n\n## Contributing\n/)
116
+ assert.equal(read('CONTRIBUTING.md'), section)
117
+ }, 'git@github.com:acme/widgets.git')
118
+ })
@@ -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.39.0
4
+ release-version: 0.41.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.39.0
6
+ release-version: 0.41.0
7
7
  ---
8
8
  **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
9
9
  # Engineering Runtime
@@ -11,6 +11,7 @@
11
11
  "golden-path",
12
12
  "test-quality",
13
13
  "better-review",
14
+ "contributing",
14
15
  "engineering-runtime"
15
16
  ],
16
17
  "dependencies": [
@@ -368,7 +369,7 @@
368
369
  "repository": "1aboveio/ai",
369
370
  "revision": "main"
370
371
  },
371
- "contentDigest": "2ab5f74d40dd23a789d969bb3a496093bb0c59e0779f93ab56520594f52263e8",
372
+ "contentDigest": "b75ef5edccf81976abc81bb9e23c234b1dee250239b671d0dfed835616a80b8b",
372
373
  "digestExcludes": []
373
374
  },
374
375
  {
@@ -381,7 +382,7 @@
381
382
  "repository": "1aboveio/ai",
382
383
  "revision": "main"
383
384
  },
384
- "contentDigest": "c2dd5e6cbcb4fe7431ff9c76f64e3161a0542adadd3e1583b40ea9311e0325f2",
385
+ "contentDigest": "04a9f779eb92ae3cb4ff2d53f9d4f4557a3640a8c589ea87bcf1905c9d7f118c",
385
386
  "digestExcludes": []
386
387
  },
387
388
  {
@@ -394,7 +395,7 @@
394
395
  "repository": "1aboveio/ai",
395
396
  "revision": "main"
396
397
  },
397
- "contentDigest": "3f03df4e4e13a0e7612a6e61f879d03f954262b71b38f4db0a74990c9d0207ef",
398
+ "contentDigest": "52580af9dbde845df15f2bc2f8425fb709a58e590dee45900bde0a610a2fb72b",
398
399
  "digestExcludes": []
399
400
  },
400
401
  {
@@ -407,7 +408,7 @@
407
408
  "repository": "1aboveio/ai",
408
409
  "revision": "main"
409
410
  },
410
- "contentDigest": "1ac457031b530489676ef9cff0e2673bf128208ea71003c48538bdd3b8a6b52c",
411
+ "contentDigest": "6eca7432eb13afac3d52dfe89cbd97edadf62f7f0c3292e16b05130fab46922a",
411
412
  "digestExcludes": []
412
413
  },
413
414
  {
@@ -420,7 +421,7 @@
420
421
  "repository": "1aboveio/ai",
421
422
  "revision": "main"
422
423
  },
423
- "contentDigest": "edecc0808b1a4e9942f7f9351a258cb55396119038133d93473f12e17c5f674d",
424
+ "contentDigest": "3e9f0fc5037e984e29a89cc9959538a16db07e2542ab746f8dfdbc2b8065928b",
424
425
  "digestExcludes": []
425
426
  },
426
427
  {
@@ -433,7 +434,7 @@
433
434
  "repository": "1aboveio/ai",
434
435
  "revision": "main"
435
436
  },
436
- "contentDigest": "1bab372a4b5d1a94582aad5621244a88d440f883454dab36a78ba761dcc542f3",
437
+ "contentDigest": "13a5da9a63e8dbb6f3843685c03db537c5e85364ba4bdb67229e481ce6898e98",
437
438
  "digestExcludes": []
438
439
  },
439
440
  {
@@ -446,7 +447,7 @@
446
447
  "repository": "1aboveio/ai",
447
448
  "revision": "main"
448
449
  },
449
- "contentDigest": "f3fdfb8a0fc271c89af97dc5ae181ffecb7ea14435f11defdcfe955cd18d3ba7",
450
+ "contentDigest": "6054351b492527244f78db5816eb07e88e70fd81c3a833f28afd63cb378d8e29",
450
451
  "digestExcludes": []
451
452
  },
452
453
  {
@@ -459,7 +460,7 @@
459
460
  "repository": "1aboveio/ai",
460
461
  "revision": "main"
461
462
  },
462
- "contentDigest": "1b2f489154398520dc81e3b900f7b602e29e3269dba41a458e61e83909d116c7",
463
+ "contentDigest": "d56284eb7931f7250932594d57b2849ae1f5969d953f3fd5f9fc30f5c39819e9",
463
464
  "digestExcludes": []
464
465
  },
465
466
  {
@@ -472,7 +473,7 @@
472
473
  "repository": "1aboveio/ai",
473
474
  "revision": "main"
474
475
  },
475
- "contentDigest": "dc14758f5fcaad60dd9f51a7f28b43954d53d687d816034ca2cda39518b7323a",
476
+ "contentDigest": "db277452380c4af72500a8343010bf1c2cd448cd3d181252ebd626787a188901",
476
477
  "digestExcludes": []
477
478
  },
478
479
  {
@@ -485,7 +486,20 @@
485
486
  "repository": "1aboveio/ai",
486
487
  "revision": "main"
487
488
  },
488
- "contentDigest": "78254999055badb626b2423046bc66704b8ebe324da83e9166242581b8d658f6",
489
+ "contentDigest": "2bb60504e38ce38deba1b18b44a17376f55b1b9380312e00387b96f0a975869a",
490
+ "digestExcludes": []
491
+ },
492
+ {
493
+ "installName": "contributing",
494
+ "ownership": "owned",
495
+ "sourcePath": "skills/engineering/contributing",
496
+ "expectedSource": {
497
+ "id": "first-party",
498
+ "type": "first-party",
499
+ "repository": "1aboveio/ai",
500
+ "revision": "main"
501
+ },
502
+ "contentDigest": "b8a5f2935b5743b3442e8666bf9b40f28696deab4b6ea4c80c5b2b70d9cc877b",
489
503
  "digestExcludes": []
490
504
  },
491
505
  {
@@ -498,13 +512,13 @@
498
512
  "repository": "1aboveio/ai",
499
513
  "revision": "main"
500
514
  },
501
- "contentDigest": "b803a7a37fb23fa514dc5abee57244950248dc3a36d90480c785cca49a49332e",
515
+ "contentDigest": "0276732bb6eab240042a5f02ad635e25d20b5342417ececf60630a65a00f3478",
502
516
  "digestExcludes": [
503
517
  "coherence/workflow.json"
504
518
  ]
505
519
  }
506
520
  ],
507
- "releaseIdentity": "d47473fb493e8ce0e8c44999c8f9dd9bad253087592ce0724d1391169bee2469",
521
+ "releaseIdentity": "c016c377bd5c173ed2ac951dcc68beb3ad0fd9ba4a64adb5466c0c7ae290c3df",
508
522
  "lifecycleAuthority": "native-skills-cli",
509
523
  "repairRecipe": {
510
524
  "id": "engineering-workflow-dependency-first",
@@ -575,16 +589,17 @@
575
589
  "golden-path",
576
590
  "test-quality",
577
591
  "better-review",
592
+ "contributing",
578
593
  "engineering-runtime"
579
594
  ],
580
595
  "commands": [
581
596
  {
582
597
  "transport": "https",
583
- "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
598
+ "command": "npx skills@1.5.22 add 1aboveio/ai --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
584
599
  },
585
600
  {
586
601
  "transport": "ssh",
587
- "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
602
+ "command": "npx skills@1.5.22 add git@github.com:1aboveio/ai.git --global --agent universal claude-code --skill harness-runtime e2e-test ensure-coverage rush-issues resolve-issues rush-release resolve-release golden-path test-quality better-review contributing engineering-runtime && npm --prefix \"$(realpath \"$HOME/.agents/skills/engineering-runtime/scripts\")\" ci --ignore-scripts"
588
603
  }
589
604
  ],
590
605
  "onFailure": {
@@ -16,6 +16,7 @@ export const WORKFLOW_OWNED_MEMBERS = deepFreeze([
16
16
  'golden-path',
17
17
  'test-quality',
18
18
  'better-review',
19
+ 'contributing',
19
20
  'engineering-runtime',
20
21
  ]);
21
22
 
@@ -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.39.0
5
+ release-version: 0.41.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.39.0
6
+ release-version: 0.41.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.39.0
6
+ release-version: 0.41.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.39.0
11
+ release-version: 0.41.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.39.0
7
+ release-version: 0.41.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.39.0
9
+ release-version: 0.41.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.39.0
9
+ release-version: 0.41.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.39.0
4
+ release-version: 0.41.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.
@@ -5,7 +5,8 @@
5
5
  // section, so no main-module guard here.
6
6
  //
7
7
  // Byte-identical copies live in test-quality (Testing conventions), github-flow
8
- // (CI conventions, Delivery) and data-catalog (Data catalog conventions);
8
+ // (CI conventions, Delivery), data-catalog (Data catalog conventions) and
9
+ // contributing (Issue tracking);
9
10
  // skills/conventions-sections.test.mjs keeps them identical and proves the sections
10
11
  // coexist in one file.
11
12
  //
@@ -22,7 +23,7 @@ const MENTIONS_CONTRIBUTING = /(?:^|[^\w-])CONTRIBUTING\.md/
22
23
  export const AGENTS_SECTION = [
23
24
  '## Contributing',
24
25
  '',
25
- `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code: tests, CI, data definitions, and what to do after each commit.`,
26
+ `Follow [${CONTRIBUTING_FILE}](${CONTRIBUTING_FILE}) when writing, reviewing, or delivering code, or creating issues: tests, CI, data definitions, issue tracking, and what to do after each commit.`,
26
27
  '',
27
28
  ].join('\n')
28
29