diff --git a/.agents/checks/architecture.md b/.agents/checks/architecture.md new file mode 100644 index 0000000..1c295d3 --- /dev/null +++ b/.agents/checks/architecture.md @@ -0,0 +1,18 @@ +# Check: architecture + +Rules lint and types can't express. Most are written in `AGENTS.md` and `CODEBASE.md`; report where a change works around one. + +## Report + +- A user-facing error thrown as a bare `Error`, or printed with `console.error()` and an exit code, instead of `CliError(code, message, hints?)` from `src/lib/errors.ts`; a new code missing from the `ErrorCode` type; `process.exit()` in a command handler. +- A new SDK call without an entry in `API_SPINNER_MESSAGES` (`src/lib/api.ts`), or a read-only one missing from `KNOWN_SAFE_API_METHODS` in `src/lib/permissions.ts` (a read-only token would block it). +- A mutating command without `--json` where it has scripting value, or `json`/`full` options added by hand instead of extending `MutationOptions` in `src/lib/options.ts`. +- Reference parsing (ids, URLs, fuzzy names) written again instead of using `src/lib/refs.ts`. +- A positional `[workspace-ref]` without the `--workspace` alias, or one that accepts both without an error. +- A new top-level command not wired into the lazy registry in `src/index.ts`. +- A barrel file, or a helper that duplicates one in `src/lib/` or `@doist/cli-core`. Where cli-core has a convention, the CLI follows it. + +## Fine + +- An exception documented next to the code, with the reason. +- A new broadly reusable helper in `src/lib/`, added to the `CODEBASE.md` catalog. diff --git a/.agents/checks/command-surface.md b/.agents/checks/command-surface.md new file mode 100644 index 0000000..cc1168f --- /dev/null +++ b/.agents/checks/command-surface.md @@ -0,0 +1,19 @@ +# Check: command surface + +What people and agents see: command and flag names, help text, human output, `--json`, `--ndjson` and `--full` shapes, error codes, and `SKILL_CONTENT`. Scripts and installed agent skills depend on every one. + +## Report + +- A renamed or removed command, flag or `--json` field, or a changed error code, without a breaking-change PR title (`feat!:`, `fix!:`). +- A command or flag change not reflected in `SKILL_CONTENT` (`src/lib/skills/content.ts`) and `skills/comms-cli/SKILL.md`, or an example there that no longer runs. +- List output that tells an id and a name apart only by colour or dimming, so the line no longer reads in `--accessible` mode. +- Meaning carried only by colour or symbols, with no `--accessible` alternative. +- Results printed to stderr or diagnostics to stdout; a spinner or prompt in `--json` or `--ndjson` mode. +- Several spinner labels for parallel fetches that build one view. They share one label. +- A flag named differently from the same flag elsewhere (`--workspace`, `--json`, `--full`, `--dry-run`, `--yes`), or a new verb where an existing one fits. +- An error message that does not name the problem, or hints without a working command. + +## Fine + +- New optional flags and new `--json` fields (additive) in a `feat:` PR. +- Help text wording fixes. diff --git a/.agents/checks/evidence.md b/.agents/checks/evidence.md new file mode 100644 index 0000000..9b84975 --- /dev/null +++ b/.agents/checks/evidence.md @@ -0,0 +1,14 @@ +# Check: evidence + +Apply to the PR description and any report from an agent. + +## Report + +- A behaviour claim ("fixed", "works", "safe", "no regressions") with no test or command that ran it. +- A "Not verified" section missing when something could not be checked: the real Comms API, output in a real terminal, the other Node version CI tests on. +- A change to shared code (`src/lib/`, command registration or global flags in `src/index.ts`, an `@doist/cli-core` or `@doist/comms-sdk` upgrade) without the one fact that makes it safe. +- A PR title whose type doesn't match the change: behaviour changes need `feat:`, `fix:` or `perf:` to release (`!` for breaking); tooling and docs use `chore:`, `ci:`, `docs:` or `test:` so they don't. + +## Fine + +- Claims about what the code shows, with the cited line. diff --git a/.agents/checks/privacy.md b/.agents/checks/privacy.md new file mode 100644 index 0000000..f199d94 --- /dev/null +++ b/.agents/checks/privacy.md @@ -0,0 +1,17 @@ +# Check: privacy and secrets + +This repository is public, and the npm package ships `dist/`, `scripts/` and `CHANGELOG.md`. + +## Report + +- A secret, API key, token or password, even an expired one. +- Real user data in fixtures, tests or docs: real names, emails, user or workspace IDs, message content or URLs copied from an account. +- Personal identifiers in docs and examples: real emails, usernames, home-directory paths, local repository names. Use placeholders (`alice@example.com`, `~/code`). +- Internal details: private hostnames, internal URLs, Doist-internal tools or documents. The staging host already used in tests as a stand-in base URL is fine. +- A new file under `scripts/` or in package.json `files` that should not be published. +- Untracked files the change doesn't need (`.env`, logs, `.tmp/`). + +## Fine + +- Made-up fixtures and cli-core's fictional test accounts (Alan Grant, Ellie Sattler). +- Public URLs: the Comms app and API, GitHub. diff --git a/.agents/checks/security.md b/.agents/checks/security.md new file mode 100644 index 0000000..8158632 --- /dev/null +++ b/.agents/checks/security.md @@ -0,0 +1,19 @@ +# Check: security + +The CLI holds the user's Comms token and reads their messages. Apply to changes in `src/` and `scripts/`. + +## Report + +- A token, `Authorization` header or `COMMS_API_TOKEN` value written to output, logs, errors, `--json` or progress events. +- A secret fetched that the command does not display. An opt-in reveal flag must gate the API call, not just the printing. +- Token storage that bypasses the keyring-backed store in `src/lib/auth.ts`, or a token written to the config file outside the documented offline fallback (`src/lib/user-records.ts`). +- A mutating SDK method added to `KNOWN_SAFE_API_METHODS` in `src/lib/permissions.ts`, which lets it run under a read-only token. +- Private channel content shown without `--include-private-channels` (or `COMMS_INCLUDE_PRIVATE_CHANNELS`): new output that skips the filtering in `src/lib/public-channels.ts`. +- A shell command built from user or API input as a string, instead of `spawn`/`execFile` with an argument list (`openEditor()` in `src/lib/input.ts` runs `$EDITOR`); a URL from API data opened in the browser without checking it is an http(s) URL. +- OAuth changes (`src/lib/auth-provider.ts`, `src/lib/scopes.ts`, `oauth/client-metadata.json`) that widen the scopes a plain `tdc auth login` asks for. +- `src/postinstall.ts` doing more than refreshing installed skills: it runs on every install. + +## Fine + +- Logging command names, durations, counts and error codes. +- Test fixtures with fake tokens. diff --git a/.agents/checks/tests.md b/.agents/checks/tests.md new file mode 100644 index 0000000..05fe821 --- /dev/null +++ b/.agents/checks/tests.md @@ -0,0 +1,19 @@ +# Check: tests + +Apply to every change that touches code or tests. The quality bar is `.agents/skills/write-tests/references/test-rules.md`. + +## Report + +- A test deleted, skipped (`.skip`, `.todo`, `xit`), or with an assertion loosened (`toEqual` → `toMatchObject`, exact arguments → `toHaveBeenCalled()`, an exact output line → `stringContaining`), without a behaviour change that explains it. +- A new snapshot test. The repository has none: tests assert exact output strings or parsed JSON. +- New behaviour with no test, or a test that would still pass with the change undone. +- A command, flag or `--json` change with no test that runs the command through `program.parseAsync`. +- A new `vi.mock` of an internal module that holds logic, or a mock of the function under test. +- An expected value computed by the code under test. +- Config that runs fewer tests: `vitest.config.ts` `include`/`exclude`, the scripts in `package.json`, the steps in `.github/workflows/test.yml`. + +## Fine + +- `.not.toHaveBeenCalled()`, guards like `toBeDefined()` before reading a value, and the `getCommsClient` mock every command test uses, as the test rules describe. +- A test changing its assertions because the behaviour changed on purpose, when the description says so. +- A refactor changing import paths, names or call sites in tests. diff --git a/.agents/scripts/instructions.test.ts b/.agents/scripts/instructions.test.ts index 1449a29..2f66fe6 100644 --- a/.agents/scripts/instructions.test.ts +++ b/.agents/scripts/instructions.test.ts @@ -166,6 +166,22 @@ it('names only test helpers that the fixtures, global-args or @doist/cli-core/te expect(named.filter((name) => !local.includes(name) && !shared.includes(name))).toEqual([]) }) +const checks = readdirSync(join(REPO_ROOT, '.agents/checks')).filter((name) => name.endsWith('.md')) + +describe.each(checks)('check %s', (check) => { + const text = readFileSync(join(REPO_ROOT, '.agents/checks', check), 'utf8') + + it('says what to report and what is fine', () => { + expect(text).toMatch(/^## Report$/m) + expect(text).toMatch(/^## Fine$/m) + }) + + it('is linked from AGENTS.md, where Doistbot finds it', () => { + const agents = readFileSync(join(REPO_ROOT, 'AGENTS.md'), 'utf8') + expect(agents).toContain(`](.agents/checks/${check})`) + }) +}) + it('has no Claude Code skill link without a skill behind it', () => { const links = readdirSync(join(REPO_ROOT, '.claude/skills')) expect(links.toSorted()).toEqual(skills.toSorted()) diff --git a/.agents/scripts/lib/review-worktree.test.ts b/.agents/scripts/lib/review-worktree.test.ts new file mode 100644 index 0000000..19dd2f3 --- /dev/null +++ b/.agents/scripts/lib/review-worktree.test.ts @@ -0,0 +1,128 @@ +import { + chmodSync, + existsSync, + readFileSync, + readlinkSync, + rmSync, + symlinkSync, + writeFileSync, +} from 'node:fs' +import { basename, join } from 'node:path' +import { afterEach, beforeEach, expect, it } from 'vitest' +import { createReviewWorktree } from './review-worktree.ts' +import { createTempRepo, type TempRepo } from './test-repo.ts' +import { codeFingerprint, snapshot } from './tree.ts' + +let repo: TempRepo +let target: string + +beforeEach(() => { + repo = createTempRepo() + repo.write('.gitignore', 'ignored/\n') + repo.write('src/a.ts', 'a\n') + repo.write('src/gone.ts', 'gone\n') + repo.write('src/staged.ts', 'old\n') + writeFileSync(join(repo.dir, 'src/image.bin'), Buffer.from([0, 1, 2, 3])) + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'initial']) + target = join(repo.dir, '..', `${basename(repo.dir)} review`) +}) + +afterEach(() => { + rmSync(target, { recursive: true, force: true }) + repo.cleanup() +}) + +it('reproduces staged, unstaged, deleted, binary and untracked changes', () => { + repo.write('src/a.ts', 'unstaged edit\n') + repo.write('src/staged.ts', 'staged edit\n') + repo.git(['add', 'src/staged.ts']) + rmSync(join(repo.dir, 'src/gone.ts')) + repo.write('src/new/untracked.ts', 'untracked\n') + writeFileSync(join(repo.dir, 'src/image.bin'), Buffer.from([0, 1, 2, 255])) + repo.write('ignored/cache.txt', 'ignored\n') + const before = codeFingerprint(snapshot(repo.dir)) + + createReviewWorktree(repo.dir, target) + + expect(codeFingerprint(snapshot(target))).toBe(before) + expect(readFileSync(join(target, 'src/a.ts'), 'utf8')).toBe('unstaged edit\n') + expect(existsSync(join(target, 'src/gone.ts'))).toBe(false) + expect([...readFileSync(join(target, 'src/image.bin'))]).toEqual([0, 1, 2, 255]) + expect(existsSync(join(target, 'ignored/cache.txt'))).toBe(false) +}) + +it('works when the user has diff.noprefix set', () => { + repo.git(['config', 'diff.noprefix', 'true']) + repo.write('src/a.ts', 'unstaged edit\n') + createReviewWorktree(repo.dir, target) + expect(readFileSync(join(target, 'src/a.ts'), 'utf8')).toBe('unstaged edit\n') +}) + +it('works with a target inside the checkout, without copying it into itself', () => { + repo.write('src/new.ts', 'untracked\n') + const inside = join(repo.dir, 'review-copy') + createReviewWorktree(repo.dir, inside) + expect(readFileSync(join(inside, 'src/new.ts'), 'utf8')).toBe('untracked\n') + expect(existsSync(join(inside, 'review-copy'))).toBe(false) +}) + +it('applies the real change when a textconv driver is configured', () => { + repo.write('.gitattributes', '*.txt diff=upper\n') + repo.write('notes.txt', 'hello\n') + repo.git(['add', '.']) + repo.git(['commit', '--quiet', '-m', 'notes']) + repo.git(['config', 'diff.upper.textconv', 'tr a-z A-Z <']) + repo.write('notes.txt', 'hello world\n') + createReviewWorktree(repo.dir, target) + expect(readFileSync(join(target, 'notes.txt'), 'utf8')).toBe('hello world\n') +}) + +it('copies an untracked relative symlink as a relative symlink', () => { + symlinkSync('../src/a.ts', join(repo.dir, 'src/link.ts')) + createReviewWorktree(repo.dir, target) + expect(readlinkSync(join(target, 'src/link.ts'))).toBe('../src/a.ts') +}) + +it('leaves the original checkout as it was', () => { + repo.write('src/a.ts', 'unstaged edit\n') + repo.write('src/new.ts', 'untracked\n') + const status = repo.git(['status', '--porcelain']).stdout + const before = codeFingerprint(snapshot(repo.dir)) + + createReviewWorktree(repo.dir, target) + writeFileSync(join(target, 'src/a.ts'), 'reviewer broke it\n') + + expect(repo.git(['status', '--porcelain']).stdout).toBe(status) + expect(codeFingerprint(snapshot(repo.dir))).toBe(before) +}) + +it('refuses a target that already exists', () => { + expect(() => createReviewWorktree(repo.dir, repo.dir)).toThrow('already exists') +}) + +// An unreadable file makes the copy fail, after the worktree exists. Root can read it anyway, and +// chmod cannot make a file unreadable on Windows. +it.skipIf(process.getuid?.() === 0 || process.platform === 'win32')( + 'cleans up when a step after creating the worktree fails', + () => { + repo.write('src/a.ts', 'unstaged edit\n') + repo.write('src/unreadable.ts', 'secret\n') + chmodSync(join(repo.dir, 'src/unreadable.ts'), 0o000) + expect(() => createReviewWorktree(repo.dir, target)).toThrow(/EACCES/) + expect(existsSync(target)).toBe(false) + expect(repo.git(['worktree', 'list']).stdout.trim().split('\n')).toHaveLength(1) + }, +) + +it('works from the command line, in a checkout whose path has a space', () => { + repo.copyFromCheckout('.agents/scripts/review-worktree.ts', '.agents/scripts/lib') + repo.git(['add', '.agents']) + repo.git(['commit', '--quiet', '-m', 'tools']) + repo.write('src/a.ts', 'unstaged edit\n') + const result = repo.run(process.execPath, ['.agents/scripts/review-worktree.ts', target]) + expect(result.stderr).toBe('') + expect(result.stdout).toContain('Review worktree ready') + expect(result.stdout).toContain(`cd '${target}' && npm ci`) + expect(readFileSync(join(target, 'src/a.ts'), 'utf8')).toBe('unstaged edit\n') +}) diff --git a/.agents/scripts/lib/review-worktree.ts b/.agents/scripts/lib/review-worktree.ts new file mode 100644 index 0000000..4c5d3a1 --- /dev/null +++ b/.agents/scripts/lib/review-worktree.ts @@ -0,0 +1,53 @@ +// A separate worktree with the current change in it, for a reviewer that needs to run or break +// code. It checks out HEAD, applies the staged and unstaged diff, and copies untracked files that +// are not ignored. It does not link node_modules: reinstalling through a symlinked node_modules +// would empty the original checkout's install. + +import { cpSync, existsSync, mkdirSync, rmSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { git } from './git.ts' + +export function createReviewWorktree(root: string, target: string): void { + if (existsSync(target)) throw new Error(`${target} already exists`) + + // Read the change before the worktree exists: a target inside the checkout would otherwise be + // listed as an untracked folder and copied into itself. Fixed prefixes and no external diff, + // textconv or colour, whatever the user's git config says, so `git apply` can read the patch. + const diff = git(root, [ + 'diff', + 'HEAD', + '--binary', + '--no-ext-diff', + '--no-textconv', + '--no-color', + '--src-prefix=a/', + '--dst-prefix=b/', + ]) + if (!diff.ok) throw new Error(`git diff failed: ${diff.stderr.trim()}`) + const untracked = git(root, ['ls-files', '-z', '--others', '--exclude-standard']) + if (!untracked.ok) throw new Error(`git ls-files failed: ${untracked.stderr.trim()}`) + + const added = git(root, ['worktree', 'add', '--quiet', '--detach', target, 'HEAD']) + if (!added.ok) throw new Error(`git worktree add failed: ${added.stderr.trim()}`) + + try { + if (diff.stdout) { + const applied = git(target, ['apply', '--whitespace=nowarn'], { input: diff.stdout }) + if (!applied.ok) throw new Error(`git apply failed: ${applied.stderr.trim()}`) + } + for (const path of untracked.stdout.split('\0').filter(Boolean)) { + mkdirSync(dirname(join(target, path)), { recursive: true }) + // verbatimSymlinks keeps a relative link relative, instead of pointing it back into + // the original checkout. + cpSync(join(root, path), join(target, path), { + recursive: true, + verbatimSymlinks: true, + }) + } + } catch (error) { + // Leave nothing behind, so a retry is not refused with "already exists". + git(root, ['worktree', 'remove', '--force', target]) + rmSync(target, { recursive: true, force: true }) + throw error + } +} diff --git a/.agents/scripts/review-worktree.ts b/.agents/scripts/review-worktree.ts new file mode 100644 index 0000000..248dc46 --- /dev/null +++ b/.agents/scripts/review-worktree.ts @@ -0,0 +1,24 @@ +// `npm run review:worktree --
+ +Done means: ++ +Decisions already made: + + +Your role: .md> + +Rules: +- The working tree at is read-only. Do not edit, stage, commit or run + scripts there. To run or break code, make your own copy: + `npm run review:worktree -- `, then `npm ci` in it; remove it when done. +- Never run the CLI against a real Comms workspace unless the brief says it is a test workspace. +- Rate each finding: cited (quote the lines), traced (followed the code path) or ran + (a test or command showed it). Report only findings you can cite at least. +- For each: severity (P1 wrong or harmful, P2 misleading, P3 minor), file:line, the + evidence, and the fix in one sentence. No praise, no summary of what is fine. +``` + +## Role notes + +- **Task review:** missing pieces, unrequested changes, unhandled cases, tests that pass with the feature broken, a command or flag change missing from `SKILL_CONTENT`, and in a refactor any changed test input or assertion. Read each new rule against every skill in `.agents/skills/`, every check in `.agents/checks/` and `AGENTS.md`, and report contradictions. +- **Blast-radius review:** name the one fact the change is safe because of. Prove it by running code in your own worktree. Look past text search: library versions in `package-lock.json`, API response shapes, `--json` output that scripts and installed skills read. +- **Code review per check:** apply only that check's "Report" and "Fine" lists. diff --git a/.claude/skills/review-changes b/.claude/skills/review-changes new file mode 120000 index 0000000..6561ae2 --- /dev/null +++ b/.claude/skills/review-changes @@ -0,0 +1 @@ +../../.agents/skills/review-changes \ No newline at end of file diff --git a/.tmp/agents/verified.json b/.tmp/agents/verified.json index 37f7f7f..61604cc 100644 --- a/.tmp/agents/verified.json +++ b/.tmp/agents/verified.json @@ -1,5 +1,5 @@ { - "fingerprint": "eae8377bebc1fb5699671b110c9eb1b24ae0a416b3ee4644193a4725c3a554ee", - "head": "81d004c744d4ec8c799d15c6d20c75d3964de1b9", - "at": "2026-11-05T11:20:19.623Z" + "fingerprint": "c3b3b61844ff7597bfa198795421f6eb8f3d8cb7338f4ce03b2b56ccd195c40c", + "head": "508fdd1db454b59ecac99170d1544cdc49097807", + "at": "2026-11-05T11:20:48.660Z" } diff --git a/AGENTS.md b/AGENTS.md index 819e3ac..648df99 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,18 @@ Use the matching skill without being asked. They live in `.agents/skills/` (Clau - `refactor`: changing structure without changing behaviour. Other tasks send restructuring here, as a separate change. - `write-tests`: writing or changing tests; `.agents/skills/write-tests/references/test-rules.md` is the quality bar. - `learn`: after a correction, to turn it into a check. +- `review-changes`: when the owner says a change is ready for a PR, or asks for a review. + +## Review checks + +Reviewers, Doistbot included, apply these to every change: + +- [Tests](.agents/checks/tests.md): not weakened, new behaviour tested. +- [Architecture](.agents/checks/architecture.md): rules lint can't express. +- [Security](.agents/checks/security.md): the token, read-only mode, private channels, shelling out. +- [Privacy and secrets](.agents/checks/privacy.md): this repository is public. +- [Command surface](.agents/checks/command-surface.md): what people, scripts and agents see. +- [Evidence](.agents/checks/evidence.md): claims backed by what ran. ## Commands diff --git a/CODEBASE.md b/CODEBASE.md index ab7a272..53cfa39 100644 --- a/CODEBASE.md +++ b/CODEBASE.md @@ -30,9 +30,11 @@ come from `@doist/cli-core`. │ # update-comms-sdk ├─ .agents/ │ ├─ skills/ # Skills for agents working on this repo (verify, fix-bug, -│ │ # build-feature, add-command, refactor, write-tests, learn) -│ └─ scripts/ # Agent tooling (verify, git hook branch guard) and its -│ # tests. Not published, unlike scripts/ +│ │ # build-feature, add-command, refactor, write-tests, learn, +│ │ # review-changes) +│ ├─ checks/ # Review checks reviewers and Doistbot apply (AGENTS.md links them) +│ └─ scripts/ # Agent tooling (verify, git hook branch guard, review +│ # worktree) and its tests. Not published, unlike scripts/ ├─ .claude/skills/ # Links to .agents/skills/, where Claude Code finds them ├─ docs/agents.md # How the agent tooling fits together ├─ AGENTS.md # Prescriptive rules (definition of done, build cmds, JSON flag, diff --git a/docs/agents.md b/docs/agents.md index ba8c9db..6136786 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -8,24 +8,28 @@ This repository is set up so coding agents prove their work before they call it 2. **`npm run verify`** runs every CI check locally and records a pass. 3. **`AGENTS.md`** tells agents what done means. Claude Code reads it through `CLAUDE.md`; Codex and other agents read it directly. 4. **Skills** in `.agents/skills/` give step-by-step procedures for recurring work. They load only when a task needs them. +5. **Review**: fresh reviewers and Doistbot check a finished change against the checks in `.agents/checks/`. ## Rules and what holds them -| Rule | Held by | Certainty | -| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | -| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | -| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | -| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | -| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | -| Tests pass before a push | `pre-push`; CI | Enforced in CI | -| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | -| `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | -| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | -| Never weaken a check to pass it | `AGENTS.md` | Asked | -| Instructions name only files, links and scripts that exist | `.agents/scripts/instructions.test.ts` | Enforced in CI | -| Every skill says when to use it and is linked for Claude Code | `.agents/scripts/instructions.test.ts` | Enforced in CI | -| Use the matching skill for each task | `AGENTS.md` | Asked | -| Tests meet the quality bar | `.agents/skills/write-tests/references/test-rules.md` | Asked | +| Rule | Held by | Certainty | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | +| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | +| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | +| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | +| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | +| Tests pass before a push | `pre-push`; CI | Enforced in CI | +| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | +| `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | +| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | +| Never weaken a check to pass it | `AGENTS.md` | Asked | +| Instructions name only files, links and scripts that exist | `.agents/scripts/instructions.test.ts` | Enforced in CI | +| Every skill says when to use it and is linked for Claude Code | `.agents/scripts/instructions.test.ts` | Enforced in CI | +| Use the matching skill for each task | `AGENTS.md` | Asked | +| Tests meet the quality bar | `.agents/skills/write-tests/references/test-rules.md` | Asked | +| Review checks say what to report and what is fine, and AGENTS.md links them | `.agents/scripts/instructions.test.ts` | Enforced in CI | +| A finished change gets a task review, a blast-radius review when shared code changed, and a code review | `review-changes` skill | Asked | +| Reviewers never edit the shared checkout | the reviewer brief; `npm run review:worktree` gives them their own | Asked | "Enforced in CI" means a pull request cannot merge without it. A local hook alone is a speed bump: `git commit --no-verify` skips it. @@ -61,23 +65,59 @@ If a pull-request workflow gains a step, `.agents/scripts/lib/steps.test.ts` fai Each skill is a short procedure with a check at the end of every step. Agents load one when the task matches its description. -| Skill | For | Ends with | -| --------------- | -------------------------------------- | ------------------------------------------------------------------- | -| `verify` | Any change about to be called done | `npm run verify`, proof matched to the change, an evidence report | -| `fix-bug` | Something broken | A test that failed on the symptom, the root cause, undo/restore | -| `build-feature` | A new command, flag or behaviour | Decisions settled up front, test-first slices, a "touches X" map | -| `add-command` | A new command or subcommand | Every file a command touches: spinner text, permissions, skill text | -| `refactor` | Structure changes, behaviour unchanged | Pinned tests, no changed test inputs or assertions | -| `write-tests` | Writing or changing tests | Tests that failed once, meeting the test rules | -| `learn` | A correction from you | A type, lint rule, test or script check that catches the mistake | +| Skill | For | Ends with | +| ---------------- | -------------------------------------- | --------------------------------------------------------------------------------------------- | +| `verify` | Any change about to be called done | `npm run verify`, proof matched to the change, an evidence report | +| `fix-bug` | Something broken | A test that failed on the symptom, the root cause, undo/restore | +| `build-feature` | A new command, flag or behaviour | Decisions settled up front, test-first slices, a "touches X" map | +| `add-command` | A new command or subcommand | Every file a command touches: spinner text, permissions, skill text | +| `refactor` | Structure changes, behaviour unchanged | Pinned tests, no changed test inputs or assertions | +| `write-tests` | Writing or changing tests | Tests that failed once, meeting the test rules | +| `learn` | A correction from you | A type, lint rule, test or script check that catches the mistake | +| `review-changes` | A change you say is ready | Task, blast-radius and code reviews; each finding fixed, dismissed with evidence or left open | The evidence report rates each claim: **said**, **cited** (a line), **traced** (followed the code), **ran** (a test or command executed it), **seen** (in the running CLI). "Fixed" or "safe" needs **ran**. Anything less is listed under "Not verified". The test rules were measured against this repository's tests first, so they accept the patterns that are fine here: `.not.toHaveBeenCalled()` for dry runs and confirmation gates, `toBeDefined()` as a guard, and the `getCommsClient` mock every command test uses. There are no snapshot tests, and the rules keep it that way. +## Review + +When you say a change is ready, the agent runs `review-changes`: + +- **Task review:** a fresh subagent gets your request in your words, what done means and the decisions made, never the author's reasoning. It looks for what is missing or unrequested. Doistbot can't do this, since it never sees the task. +- **Blast-radius review:** only when shared code changed (`src/lib/`, registration and global flags in `src/index.ts`, the cli-core or SDK version, dependencies, build config). It names the one fact that makes the change safe and proves it by running code. +- **Code review:** Doistbot locally (`doistbot review --json`, or `--base ` in a stack) when version 1.0.12+ is installed and `doistbot doctor` passes. Otherwise one subagent per check in `.agents/checks/`. Doistbot reads `AGENTS.md` and its links, so the checks apply to its pull request reviews too. + +Findings are fixed, dismissed with evidence (a line or a test run, never an argument), or left open for you. Reviewers that need to run code get their own worktree from `npm run review:worktree -- `; the shared one stays read-only. + +The checks cover tests, architecture, security, privacy, the command surface and evidence. The security check includes private channels: nothing from one is shown without `--include-private-channels`. Two kinds Doist uses elsewhere don't apply here: there are no translations and no database migrations. + +A review costs several agent runs, so it runs when you ask, not on every change. A Doistbot run with a failed provider (`providerFailures`) is partial; the agent should say so. + +## How to ask an agent + +Give it: + +- **the goal**, in a sentence; +- **a done check** that can pass or fail ("`tdc inbox --json` lists only unread threads"); +- **the proof you want** (a failing test first, a real `node dist/index.js` run on a test workspace); +- **facts you know** and **real constraints** (a deadline, a flag that must not change). + +Leave out the method and your theory of the cause. For a vague report, ask the agent to restate it first. Start a new session for unrelated work. + +| To start… | Say | +| ---------- | ------------------------------------------------------------------------------------------------------------------ | +| a bug fix | "Fix: . Command: . Expected: ." (`fix-bug`) | +| a feature | "Add . Done when ." (`build-feature`) | +| a refactor | "Refactor so ." (`refactor`) | +| a review | "Ready for a PR." (`review-changes`) | +| a release | "Ready to release." Check the PR title type: `feat:`, `fix:`, `perf:` and breaking changes publish; others do not. | + +Your part: answer the decision questions, and read the evidence report, especially "Not verified". + ## Where the tooling lives -- `.agents/scripts/` holds scripts and their tests, next to the skills. It is not under `scripts/` because `scripts/` ships in the npm package. +- `.agents/scripts/` holds scripts and their tests, next to the skills and review checks. It is not under `scripts/` because `scripts/` ships in the npm package. - Skills live in `.agents/skills/`, where Codex reads them. Claude Code reads them through the symlinks in `.claude/skills/`; a test keeps the two in step. - The tooling runs straight from TypeScript with Node's type stripping, so it only uses erasable syntax (`.agents/scripts/tsconfig.json` enforces this). `npm run type-check` covers it, and `npm run lint:check` lints it. - Tests run in `npm test` and CI. They copy the tools into throwaway git repositories and never touch your checkout. A test helper clears the variables git exports to hooks, since `npm test` itself runs inside `pre-push`. diff --git a/package.json b/package.json index 3d0c4a4..a1daf22 100644 --- a/package.json +++ b/package.json @@ -20,6 +20,7 @@ "test": "vitest run", "test:watch": "vitest", "verify": "node .agents/scripts/verify.ts", + "review:worktree": "node .agents/scripts/review-worktree.ts", "prepublishOnly": "npm run build && npm test", "prepare": "lefthook install --reset-hooks-path" },