@wringer/gunshi 0.1.0 → 0.2.0

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 (47) hide show
  1. package/README.md +45 -2
  2. package/dist/build-lint-command.d.ts +2 -0
  3. package/dist/build-linted-wringer.d.ts +2 -0
  4. package/dist/collect-dead-globs.d.ts +6 -0
  5. package/dist/collect-journey-commands.d.ts +11 -0
  6. package/dist/collect-lint-files.d.ts +11 -0
  7. package/dist/find-skill-copy-refusal.d.ts +8 -0
  8. package/dist/index.d.ts +1 -0
  9. package/dist/parse-shell-words.d.ts +1 -0
  10. package/dist/parse-skill-install-args.d.ts +3 -0
  11. package/dist/parse-skill-metadata.d.ts +9 -0
  12. package/dist/resolve-invocation.d.ts +3 -0
  13. package/dist/resolve-journey-problem.d.ts +2 -0
  14. package/dist/resolve-lint-failures.d.ts +26 -0
  15. package/dist/run-cli.d.ts +1 -2
  16. package/dist/run-verify.d.ts +4 -1
  17. package/dist/template-version.d.ts +1 -0
  18. package/dist/wringer-gunshi.d.ts +2 -0
  19. package/dist/write-skill-copy.d.ts +12 -0
  20. package/package.json +13 -6
  21. package/skills/wringer/SKILL.md +143 -0
  22. package/skills/wringer/references/create.md +90 -0
  23. package/skills/wringer/references/fresh-subagent-brief.md +34 -0
  24. package/skills/wringer/references/maintain.md +78 -0
  25. package/skills/wringer/references/prove.md +42 -0
  26. package/skills/wringer/template/verify/SKILL.md +176 -0
  27. package/skills/wringer/template/verify/references/feature-map.md +17 -0
  28. package/skills/wringer/template/verify-registry.ts +83 -0
  29. package/skills/wringer/template/verify.ts +6 -0
  30. package/src/build-lint-command.ts +91 -0
  31. package/src/build-linted-wringer.ts +16 -0
  32. package/src/collect-dead-globs.ts +21 -0
  33. package/src/collect-journey-commands.ts +140 -0
  34. package/src/collect-lint-files.ts +36 -0
  35. package/src/find-skill-copy-refusal.ts +34 -0
  36. package/src/index.ts +1 -0
  37. package/src/parse-shell-words.ts +67 -0
  38. package/src/parse-skill-install-args.ts +25 -0
  39. package/src/parse-skill-metadata.ts +56 -0
  40. package/src/resolve-invocation.ts +94 -0
  41. package/src/resolve-journey-problem.ts +64 -0
  42. package/src/resolve-lint-failures.ts +111 -0
  43. package/src/run-cli.ts +6 -97
  44. package/src/run-verify.ts +27 -16
  45. package/src/template-version.ts +3 -0
  46. package/src/wringer-gunshi.ts +27 -0
  47. package/src/write-skill-copy.ts +75 -0
package/README.md CHANGED
@@ -26,11 +26,54 @@ Call `runVerify` from the repo's verify script with the registry that `@wringer/
26
26
  import { runVerify } from '@wringer/gunshi';
27
27
  import { registry } from './registry.ts';
28
28
 
29
- await runVerify(registry);
29
+ await runVerify(registry, { skill: '.claude/skills/verify' });
30
30
  ```
31
31
 
32
32
  Run it as `bun verify.ts <command>`, for example `bun verify.ts up` or
33
- `bun verify.ts action seed --count 3`.
33
+ `bun verify.ts action seed --count 3`. The CLI lists the built-in commands, such as `up`, `doctor`
34
+ and `lint`, beside the commands that the registry declares and that its drivers add. A registry
35
+ can't declare a command named `lint`: `runVerify` throws `Two commands share the name`, as `build()`
36
+ does on any duplicate name.
37
+
38
+ `skill` is the path, from the repo root, of the folder that holds the repo's verify skill: the
39
+ Markdown that tells the repo's agents how to use each feature. `lint` reads that folder. The path
40
+ defaults to `.claude/skills/verify`.
41
+
42
+ ## Agent skill
43
+
44
+ The package ships an agent skill in `skills/wringer/`. It walks an agent through adding a verify
45
+ CLI, a feature map and a verify skill to a repo, and through the checks that prove them. Its
46
+ `template/` folder holds the example files for the repo's own verify skill, which the agent writes.
47
+
48
+ The install command deletes the folder it installs to, so move any edits out of the repo's copy
49
+ first. After you install or upgrade the package, run the install command from the repo root:
50
+
51
+ ```bash
52
+ bunx @wringer/gunshi skill install
53
+ ```
54
+
55
+ It copies the skill from the installed package to `.claude/skills/wringer`, or to `--dir <path>`. It
56
+ refuses a folder that is not a copy of this agent skill, and exits with code 2.
57
+
58
+ ## lint
59
+
60
+ `bun verify.ts lint` checks the feature map and the verify skill without starting the app, so CI can
61
+ run it on a fresh checkout. It exits with code 1, with `check-failed` in its envelope's
62
+ `error.code`, when it finds any of these:
63
+
64
+ - a feature's `paths` glob that matches no tracked file, and no untracked file outside git's ignore
65
+ rules;
66
+ - a line in a fenced code block of the verify skill's Markdown files that calls the CLI and fails to
67
+ parse, whose arguments fail the command's schema, or that names a feature or a target the registry
68
+ lacks;
69
+ - a skill folder with no `SKILL.md`;
70
+ - a verify skill whose frontmatter lacks `metadata.wringer-template` or `metadata.wringer-command`,
71
+ or whose `metadata.wringer-template` differs from the template version that this package ships.
72
+ The agent skill's upgrade steps bring the verify skill to the shipped version.
73
+
74
+ `metadata.wringer-command` holds the words that call the CLI, such as `bun verify`. `lint` checks
75
+ only the code block lines that start with those words, after an optional `$ ` prompt and environment
76
+ assignments.
34
77
 
35
78
  ## Behaviour
36
79
 
@@ -0,0 +1,2 @@
1
+ import type { RegisteredCommand } from '@wringer/core';
2
+ export declare function buildLintCommand(skillFolder: string): RegisteredCommand;
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function buildLintedWringer(wringer: Wringer, skillFolder: string): Wringer;
@@ -0,0 +1,6 @@
1
+ import type { FeatureDefinition } from '@wringer/core';
2
+ export interface DeadGlob {
3
+ readonly feature: string;
4
+ readonly glob: string;
5
+ }
6
+ export declare function collectDeadGlobs(features: readonly FeatureDefinition[], files: readonly string[]): readonly DeadGlob[];
@@ -0,0 +1,11 @@
1
+ export interface MarkdownFile {
2
+ readonly path: string;
3
+ readonly text: string;
4
+ }
5
+ export interface JourneyCommand {
6
+ readonly path: string;
7
+ readonly line: number;
8
+ readonly text: string;
9
+ readonly argv: readonly string[] | null;
10
+ }
11
+ export declare function collectJourneyCommands(files: readonly MarkdownFile[], cliWords: readonly string[]): readonly JourneyCommand[];
@@ -0,0 +1,11 @@
1
+ export interface LintFileListing {
2
+ readonly listed: string;
3
+ readonly deleted: string;
4
+ readonly skillFolder: string;
5
+ }
6
+ export interface LintFiles {
7
+ readonly files: readonly string[];
8
+ readonly skillFolder: string;
9
+ readonly skillMarkdown: readonly string[];
10
+ }
11
+ export declare function collectLintFiles(listing: LintFileListing): LintFiles;
@@ -0,0 +1,8 @@
1
+ export type DestinationState = 'absent' | 'wringer-skill' | 'other';
2
+ export interface SkillCopyPlan {
3
+ readonly source: string;
4
+ readonly destination: string;
5
+ readonly cwd: string;
6
+ readonly state: DestinationState;
7
+ }
8
+ export declare function findSkillCopyRefusal(plan: SkillCopyPlan): string | null;
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
1
  export { runCLI } from './run-cli.ts';
2
2
  export type { CLIPorts } from './run-cli.ts';
3
3
  export { runVerify } from './run-verify.ts';
4
+ export type { VerifyOptions } from './run-verify.ts';
@@ -0,0 +1 @@
1
+ export declare function parseShellWords(line: string): readonly string[] | null;
@@ -0,0 +1,3 @@
1
+ export declare function parseSkillInstallArgs(argv: readonly string[]): {
2
+ destination: string;
3
+ } | null;
@@ -0,0 +1,9 @@
1
+ export type SkillMetadata = {
2
+ readonly ok: true;
3
+ readonly templateVersion: number;
4
+ readonly cliWords: readonly string[];
5
+ } | {
6
+ readonly ok: false;
7
+ readonly reason: string;
8
+ };
9
+ export declare function parseSkillMetadata(text: string): SkillMetadata;
@@ -0,0 +1,3 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ import type { ParsedInvocation } from './pick-cli-outcome.ts';
3
+ export declare function resolveInvocation(wringer: Wringer, argv: readonly string[]): Promise<ParsedInvocation>;
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function resolveJourneyProblem(wringer: Wringer, argv: readonly string[]): Promise<string | null>;
@@ -0,0 +1,26 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ import { z } from 'zod';
3
+ import type { MarkdownFile } from './collect-journey-commands.ts';
4
+ export declare const lintFailureSchema: z.ZodObject<{
5
+ check: z.ZodEnum<{
6
+ journey: "journey";
7
+ paths: "paths";
8
+ template: "template";
9
+ }>;
10
+ where: z.ZodString;
11
+ problem: z.ZodString;
12
+ }, z.core.$strict>;
13
+ type LintFailure = z.infer<typeof lintFailureSchema>;
14
+ export interface LintInput {
15
+ readonly wringer: Wringer;
16
+ readonly files: readonly string[];
17
+ readonly skillPath: string;
18
+ readonly skillFiles: readonly MarkdownFile[];
19
+ readonly templateVersion: number;
20
+ }
21
+ export interface LintResult {
22
+ readonly commands: number;
23
+ readonly failures: readonly LintFailure[];
24
+ }
25
+ export declare function resolveLintFailures(input: LintInput): Promise<LintResult>;
26
+ export {};
package/dist/run-cli.d.ts CHANGED
@@ -1,5 +1,4 @@
1
- import { WringerError } from '@wringer/core';
2
- import type { RepoHost, StatePort, SupervisorPort, Wringer } from '@wringer/core';
1
+ import type { RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
3
2
  interface RepoPorts {
4
3
  readonly state: StatePort;
5
4
  readonly repoHost: RepoHost;
@@ -1,2 +1,5 @@
1
1
  import type { Wringer } from '@wringer/core';
2
- export declare function runVerify(wringer: Wringer): Promise<void>;
2
+ export interface VerifyOptions {
3
+ readonly skill?: string | undefined;
4
+ }
5
+ export declare function runVerify(wringer: Wringer, options?: VerifyOptions): Promise<void>;
@@ -0,0 +1 @@
1
+ export declare const templateVersion = 1;
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env bun
2
+ export {};
@@ -0,0 +1,12 @@
1
+ export interface SkillCopyPaths {
2
+ readonly source: string;
3
+ readonly destination: string;
4
+ readonly cwd: string;
5
+ }
6
+ export type SkillCopyResult = {
7
+ readonly ok: true;
8
+ } | {
9
+ readonly ok: false;
10
+ readonly reason: string;
11
+ };
12
+ export declare function writeSkillCopy(paths: SkillCopyPaths): Promise<SkillCopyResult>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wringer/gunshi",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "The gunshi adapter for wringer: turns a wringer registry into a CLI",
5
5
  "homepage": "https://github.com/zgeoff/wringer/tree/main/packages/gunshi#readme",
6
6
  "bugs": "https://github.com/zgeoff/wringer/issues",
@@ -10,11 +10,16 @@
10
10
  "url": "git+https://github.com/zgeoff/wringer.git",
11
11
  "directory": "packages/gunshi"
12
12
  },
13
+ "bin": {
14
+ "wringer-gunshi": "./src/wringer-gunshi.ts"
15
+ },
13
16
  "files": [
14
17
  "src",
15
18
  "!src/**/*.test.ts",
16
19
  "dist",
17
- "!src/test-utils"
20
+ "!src/test-utils",
21
+ "skills",
22
+ "!skills/**/*.test.ts"
18
23
  ],
19
24
  "type": "module",
20
25
  "exports": {
@@ -32,15 +37,17 @@
32
37
  },
33
38
  "dependencies": {
34
39
  "gunshi": "0.37.3",
40
+ "tiny-invariant": "1.3.3",
41
+ "ts-pattern": "5.9.2",
35
42
  "zod": "4.6.7"
36
43
  },
37
44
  "devDependencies": {
38
- "@wringer/core": "0.1.1",
39
- "@zgeoff/testing": "0.2.1",
40
- "tiny-invariant": "1.3.3"
45
+ "@wringer/core": "0.2.0",
46
+ "@wringer/http": "0.1.2",
47
+ "@zgeoff/testing": "0.3.0"
41
48
  },
42
49
  "peerDependencies": {
43
- "@wringer/core": "0.1.1"
50
+ "@wringer/core": "0.2.0"
44
51
  },
45
52
  "engines": {
46
53
  "bun": ">=1.3"
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: wringer
3
+ description:
4
+ "Builds a repo's verify CLI, feature map and verify skill on wringer, proves them, and keeps them
5
+ true. Load it to add wringer to a repo, to prove a verify CLI before its PR, when `verify lint`
6
+ fails, or when a new @wringer/gunshi ships a new template version."
7
+ ---
8
+
9
+ # Build a verify CLI with wringer
10
+
11
+ Give the repo's agents one way to use its real app and keep the evidence of what they checked. Build
12
+ these in the repo:
13
+
14
+ - a verify CLI on the `@wringer/*` packages, which an agent runs as `bun verify <command>`;
15
+ - its registry: the code that declares the targets, the drivers, the actions, the doctor checks and
16
+ the features, with each feature's `paths` globs, and the ignore list, set with `.ignore`: the
17
+ globs of the files the running app never reads;
18
+ - a `verify` skill, with a feature map in its `references/feature-map.md` that gives each feature's
19
+ journey.
20
+
21
+ These terms hold across this skill and its references:
22
+
23
+ | Term | Meaning |
24
+ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | target | where the app runs: `local`, which the CLI starts, or an instance it attaches to |
26
+ | read-only | a target's access that refuses each write with exit code 3 |
27
+ | driver | a package that adds a group of commands, such as `@wringer/http` and `http request` |
28
+ | action | a named step of the repo's own, run as `bun verify action <name>` |
29
+ | doctor | `bun verify doctor`: the checks that must pass before any command that touches the app |
30
+ | journey | the `bun verify` commands that use one feature, and the end state that shows it works |
31
+ | verdict | what `bun verify done` records: the feature works on the current code |
32
+ | gate | `bun verify gate` in CI: it fails a PR on a changed feature without a verdict, and on a changed file outside every `paths` glob and the ignore list |
33
+ | report | the output of `bun verify report --human`, which the PR body holds for the gate |
34
+
35
+ Then prove them, and wire the checks that keep them true. Hand back the PR that adds them, with the
36
+ proof in its description. The mistakes that cost the most:
37
+
38
+ - **Calling it done before a fresh agent uses it.** You know the app; the repo's next agent knows
39
+ only the `verify` skill. Run a subagent with none of your context to show that the skill works.
40
+ - **Copying commands into the `verify` skill.** The CLI lists its own commands in `--help`, and a
41
+ copy goes stale. Point at `--help`, and write only what the help can't say.
42
+ - **A `paths` glob that matches no file.** The files it should cover then fail the gate as unmapped,
43
+ unless another feature's glob covers them. Run `bun verify lint` to find one.
44
+ - **Writing a repo's own choices outside the `<!-- repo -->` blocks of the `verify` skill.** An
45
+ upgrade of the template replaces every line outside them. Put each choice, such as where an agent
46
+ reports a refused write, in a block or in the repo's code.
47
+
48
+ ## Key rules
49
+
50
+ - [Install the skill](#install-the-skill): copy it from `@wringer/gunshi`, at the version the repo
51
+ installs.
52
+ - [The template](#the-template): the files to copy, with fixed parts and repo parts.
53
+ - [Create](#create): read the repo, then write the CLI, the actions, the checks, 3 to 5 features,
54
+ the ignore list and the `verify` skill.
55
+ - [Prove](#prove): doctor passes, a fresh subagent reaches `done` on every feature, and the CLI
56
+ refuses what it should.
57
+ - [Maintain](#maintain): the gate and `lint` in CI, and a template upgrade when `lint` asks.
58
+
59
+ ## References
60
+
61
+ - [Create](./references/create.md): writing the CLI, the registry and the `verify` skill in a repo.
62
+ - [Prove](./references/prove.md): the proof steps and what each shows in the PR.
63
+ - [Fresh subagent brief](./references/fresh-subagent-brief.md): the brief to give the subagent in
64
+ the prove flow.
65
+ - [Maintain](./references/maintain.md): wiring the gate and `lint` into CI, and upgrading the
66
+ template.
67
+
68
+ ## Install the skill
69
+
70
+ This skill ships inside `@wringer/gunshi`, so its version matches the packages the repo installs.
71
+ These commands put it in `.claude/skills/wringer/`, where an agent can load it, and replace any
72
+ older copy there. Commit that folder with the rest of the work:
73
+
74
+ ```bash
75
+ bun add --dev --exact @wringer/core @wringer/gunshi zod
76
+ bunx @wringer/gunshi skill install
77
+ ```
78
+
79
+ Run the second command again after each upgrade of `@wringer/gunshi`.
80
+
81
+ The CLI runs on Bun. When the repo installs packages with another package manager, use it for
82
+ `bun add` and `bunx`, such as `pnpm add` and `pnpm dlx`. Also use it in the `verify` skill's
83
+ `metadata.wringer-command`, such as `pnpm verify`. The `verify` script in `package.json` still runs
84
+ the CLI with `bun`.
85
+
86
+ ## The template
87
+
88
+ [`template/`](./template/) holds a working example for an invented app, Larder:
89
+
90
+ | File | Copy to | Holds |
91
+ | ----------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------- |
92
+ | [`verify.ts`](./template/verify.ts) | `scripts/verify/verify.ts` | the entry point that calls `runVerify` |
93
+ | [`verify-registry.ts`](./template/verify-registry.ts) | `scripts/verify/verify-registry.ts` | targets, a driver, an action, a command, a check, a feature |
94
+ | [`verify/`](./template/verify/) | `.claude/skills/verify/` | the repo's `verify` skill, and its feature map in `references/` |
95
+
96
+ Skip `verify-registry.test.ts` in `template/`: it tests the template inside wringer.
97
+
98
+ These locations are defaults. When you change one, change each place that refers to it:
99
+
100
+ - the folder `scripts/verify/`: the `verify` script's path in `package.json`, and its glob in the
101
+ registry's `.ignore` list;
102
+ - the skill folder: `runVerify`'s `skill` option, a path from the repo root;
103
+ - the script name `verify`: the `package.json` script and the skill's `metadata.wringer-command`,
104
+ such as `bun verify`.
105
+
106
+ In the `verify` skill's `SKILL.md`, each `<!-- repo: <part> -->` block ends at `<!-- /repo -->` and
107
+ holds what only this repo knows. Rewrite those blocks, the frontmatter's `name` and `description`,
108
+ and the `#` title. Keep every other line. The repo owns `references/feature-map.md` whole. Keep
109
+ `metadata.wringer-template` as the template has it: `lint` compares it with the version that
110
+ `@wringer/gunshi` ships.
111
+
112
+ ## Create
113
+
114
+ Read how the app starts, what it prints when it is ready, and which state it keeps. Then follow
115
+ [Create](./references/create.md): it ends with 3 to 5 features in the registry, each with a journey
116
+ in the `verify` skill, an ignore list for the files with no runtime effect, and `bun verify lint`
117
+ passing.
118
+
119
+ ## Prove
120
+
121
+ The work is done only when each of these holds. [Prove](./references/prove.md) gives the commands.
122
+
123
+ 1. `bun verify doctor` passes on `local`.
124
+ 2. A fresh subagent that loads only the new `verify` skill reaches `done` on every feature. A new
125
+ feature map needs one pass by an agent who did not write it, and this run is that pass.
126
+ 3. After an edit to a file that a feature's `paths` match, a command that touches the app fails with
127
+ `doctor-required`. A read-only target, if the repo has one, refuses one write with `read-only`.
128
+ 4. The whole report is in the description of the PR that adds the CLI. The gate reads the report
129
+ from the HTML comment at the report's end.
130
+
131
+ ## Maintain
132
+
133
+ Wire these into the repo, as [Maintain](./references/maintain.md) shows:
134
+
135
+ - **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict recorded on the
136
+ PR's latest code. A PR that touches a file outside every feature's `paths` and the ignore list
137
+ fails until you add the file to one of them.
138
+ - **`lint` in CI.** It needs no running app.
139
+ - **A journey fixed with its feature.** A PR that changes a feature fixes the feature's journey.
140
+
141
+ Add no scheduled job. The gate checks a feature each time a PR changes it.
142
+
143
+ **Reply:** the PR link, and for each prove step, the command and the output lines that show it held.
@@ -0,0 +1,90 @@
1
+ # Create
2
+
3
+ Add the verify CLI, its registry and the repo's `verify` skill. The registry is the file that
4
+ declares the targets, drivers, actions, repo commands, doctor checks and features;
5
+ [`verify-registry.ts`](../template/verify-registry.ts) shows one of each, on the builder that
6
+ `createWringer` returns.
7
+
8
+ The mistakes that cost the most:
9
+
10
+ - **Leaving a read unmarked.** A repo command is a write unless it declares `effect: 'read'`, and an
11
+ action must declare its effect. A read-only target refuses each write with exit code 3.
12
+ - **A glob relative to a package.** Write each feature's `paths` globs relative to the repo root, as
13
+ `git ls-files` prints paths. In a monorepo, a glob relative to a package folder matches nothing.
14
+ - **Ignoring a file that changes behaviour.** Ignore only files the running app never reads, such as
15
+ docs and tests. The gate skips a file that an ignore glob matches, even when a feature's `paths`
16
+ match it too, so a change to it never needs a verdict.
17
+ - **A placeholder in a journey.** In the `verify` skill's fenced code blocks, `bun verify lint`
18
+ parses each line that starts with `bun verify`, and reads `<name>` as a shell redirect. Write each
19
+ such line as a command that runs, and put a command with a placeholder in inline code.
20
+ - **Matching a plain-text ready line as a string.** The launch target's `ready` function gets a JSON
21
+ object line as that object, and any other line as `{ message: <the line> }`. Match plain text on
22
+ `line['message']`.
23
+
24
+ ## Steps
25
+
26
+ 1. Install each driver the app needs, at an exact version, such as
27
+ `bun add --dev --exact @wringer/http`. Expect: each one in `devDependencies`.
28
+
29
+ | Driver | Drives |
30
+ | ------------------ | -------------------------------------------- |
31
+ | `@wringer/browser` | a page, through its accessibility tree |
32
+ | `@wringer/http` | the app's HTTP API |
33
+ | `@wringer/db` | SQL on the app's SQLite or Postgres database |
34
+ | `@wringer/stream` | the app's logs, recorded for the whole run |
35
+
36
+ Each driver adds its own commands and its own doctor check. Its README in `node_modules/` gives
37
+ its config for a target.
38
+
39
+ 2. Add `.wringer/` to `.gitignore`. The CLI keeps each run's state and evidence there.
40
+ 3. Copy [`verify.ts`](../template/verify.ts) and
41
+ [`verify-registry.ts`](../template/verify-registry.ts) into `scripts/verify/`. Add
42
+ `"verify": "bun scripts/verify/verify.ts"` to the `scripts` of `package.json`. Expect:
43
+ `bun verify --help` lists the template's commands.
44
+ 4. In `verify-registry.ts`, write the `local` target with `mode: 'launch'` and
45
+ `access: 'read-write'`. Its `launch` function returns:
46
+ - `command`: the command a developer runs to start the app;
47
+ - `env`: the app's environment. Point the app's state at `ctx.runDirectory` here, such as a
48
+ SQLite file, so each run starts clean. For a database server, name a database per run;
49
+ - `ready`: a function that returns the app's endpoints once a line shows the app is ready, such
50
+ as `{ web: 'http://127.0.0.1:4100' }`, and `null` before. The drivers use the `web` endpoint
51
+ unless a driver's config sets another `endpoint`.
52
+ 5. Write a target with `mode: 'attach'` for each instance that runs apart from the CLI, such as a
53
+ staging or a production deployment. Its `endpoints` function returns the instance's URLs. Give a
54
+ target `access: 'read-only'` when agents must never write there, such as production, and a
55
+ `refusalHint` that tells the agent where to report a write it needed.
56
+ 6. Under each target's `drivers`, give a config for each driver the target allows. A target with no
57
+ config for a driver refuses that driver's commands.
58
+ 7. Write an action with `.action` for each setup step a journey needs and a user can't do quickly in
59
+ the app, such as seeding a record. The CLI runs it as `bun verify action <name>`.
60
+ 8. Write a repo command with `.command` for a read that a journey checks, such as a count.
61
+ 9. Write a doctor check with `.check` for each thing that must hold before a journey means anything,
62
+ such as an API that answers. Then run `bun verify up`, then `bun verify doctor`. Expect:
63
+ `data.passed: true`. Run `bun verify down`.
64
+ 10. Write 3 to 5 features with `.feature`, each with `name`, `summary` and `paths`. Pick the
65
+ journeys users take most, from the app's routes and its README, and give each feature the globs
66
+ of the files that change its behaviour.
67
+ 11. The gate fails a PR that changes a file matched by neither a feature's `paths` nor an ignore
68
+ glob. Call `.ignore` with the globs of the files the running app never reads, such as `docs/**`,
69
+ `**/*.md`, `**/*.test.ts`, `.github/**`, `.claude/**` and `scripts/verify/**`. Add each other
70
+ file to the `paths` of each feature whose behaviour it changes: a file such as `package.json`
71
+ changes every feature. Expect: each file that `git ls-files` prints matches a feature's `paths`
72
+ or an ignore glob.
73
+ 12. Copy [`template/verify/`](../template/verify/) to `.claude/skills/verify/`. Rewrite the
74
+ frontmatter's `name` and `description` and the `#` title for the app. Set
75
+ `metadata.wringer-command` to the command that runs the script, `bun verify` by default. Rewrite
76
+ each `<!-- repo: <part> -->` block:
77
+ - `targets`: one row per target, with the command that starts a run, and what to do on a
78
+ refusal.
79
+ - `commands`: what `--help` can't say about the actions and repo commands, such as the order to
80
+ run them in.
81
+ - `registry`: the path of the registry file.
82
+
83
+ Then rewrite `references/feature-map.md` with one `##` entry per feature, in the template's
84
+ form: what it does, how a user reaches it, its journey as a block of commands that run as
85
+ written, and its end state.
86
+
87
+ 13. Run `bun verify lint`. Expect: `ok: true`, and `data.commands`, the count of journey lines it
88
+ parsed, above 0. A count of 0 means it found no journey.
89
+ 14. Run `bun verify --help`, then `bun verify <group> --help` for each group it lists, such as
90
+ `action`. Expect: every action and repo command, each marked `[read]` or `[write]`.
@@ -0,0 +1,34 @@
1
+ # Fresh subagent brief
2
+
3
+ Send the brief below to a new general-purpose subagent. Never use a fork: a fork carries your
4
+ context, and the subagent must know only what the repo's `verify` skill tells it. Fill in the three
5
+ placeholders, and add nothing else. A fact you add about the app or the CLI hides a gap in the
6
+ skill.
7
+
8
+ - `<repo root>`: the absolute path of the repo.
9
+ - `<skill path>`: the absolute path of the `SKILL.md` of the repo's `verify` skill.
10
+ - `<features>`: every feature name that `bun verify features` lists, comma-separated.
11
+
12
+ ```text
13
+ Load the skill at <skill path> and read it whole. It tells you how to use this repo's app with
14
+ its verify CLI.
15
+
16
+ Your task: for each of these features, run the CLI's `done` command and get exit code 0:
17
+ <features>.
18
+
19
+ - Use only what the skill says and what the CLI prints, `--help` included. Read no source code.
20
+ - Run every command from the repo root, <repo root>.
21
+ - Leave the app's code and the skill unchanged.
22
+ - When you finish, stop the app with the command the skill gives.
23
+
24
+ Reply with:
25
+ 1. For each feature: each command you ran, its exit code, and the `ok`, `feature` and
26
+ `data.fingerprint` fields of the JSON that `done` printed.
27
+ 2. Each place where the skill left you to guess, was wrong, or sent you to the source: the line of
28
+ the skill, what you needed, and what you did instead. Write "none" when there was none.
29
+ ```
30
+
31
+ When the subagent names a gap, fix the `verify` skill, or the CLI when its help or an error caused
32
+ the gap. Then send the same brief to a new subagent. When a `done` fails and the subagent names no
33
+ gap, find the cause before you change the skill: the app or the registry may be wrong. Stop when one
34
+ subagent gets exit code 0 from `done` on every feature and names no gap.
@@ -0,0 +1,78 @@
1
+ # Maintain
2
+
3
+ Wire `bun verify lint` and the gate into the repo's CI, fix a journey when its feature changes, and
4
+ upgrade the `verify` skill when `lint` reports an older template.
5
+
6
+ The mistakes that cost the most:
7
+
8
+ - **A shallow checkout.** The gate needs the merge base with the PR's base branch, so it fails on a
9
+ checkout without the full history.
10
+ - **No run on a body edit.** The gate reads the report from the PR body, so a run that skips the
11
+ `edited` event misses the report an author pastes later.
12
+ - **A nested copy.** `cp -R` into a folder that exists nests the copy inside it. Move the old
13
+ `verify` skill folder away first, as step 2 of the upgrade does.
14
+ `bunx @wringer/gunshi skill install` replaces the wringer skill's folder itself, so that folder
15
+ needs no move.
16
+
17
+ ## Wire the checks into CI
18
+
19
+ `bun verify lint` and `bun verify gate --base <ref> --body-file <file>` need no running app, so they
20
+ run in any job that has the repo's dependencies. The gate reads the last report block in the PR body
21
+ and works out the code's fingerprint itself. It fails with exit code 1 in two cases:
22
+
23
+ - A changed feature has no verdict, or a verdict for other code.
24
+ - A changed file matches neither a feature's `paths` nor a glob in the ignore list, which the
25
+ registry sets with `.ignore`. `bun verify gate` lists each such file in `data.unmapped`. When the
26
+ running app never reads the file, add it to the ignore list. Otherwise add it to a feature's
27
+ `paths`.
28
+
29
+ Add a workflow like this one. When the repo's other workflows pin each action to a commit SHA, pin
30
+ these the same way.
31
+
32
+ ```yaml
33
+ on:
34
+ pull_request:
35
+ types: [opened, synchronize, reopened, edited]
36
+ jobs:
37
+ verify:
38
+ runs-on: ubuntu-latest
39
+ steps:
40
+ - uses: actions/checkout@v4
41
+ with:
42
+ fetch-depth: 0 # the gate needs the merge base
43
+ - uses: oven-sh/setup-bun@v2
44
+ - run: bun install --frozen-lockfile
45
+ - run: bun verify lint
46
+ - run: jq -r '.pull_request.body // ""' "$GITHUB_EVENT_PATH" > "$RUNNER_TEMP/pr-body.md"
47
+ - run: bun verify gate --base "origin/$GITHUB_BASE_REF" --body-file "$RUNNER_TEMP/pr-body.md"
48
+ ```
49
+
50
+ Keep it a workflow of its own, so a body edit reruns only this job.
51
+
52
+ ## Fix a drifted journey
53
+
54
+ A journey breaks when a change to its feature, such as a renamed button, makes a command of its
55
+ journey fail, or leaves the app different from the end state the journey expects. Fix the feature's
56
+ journey in the `verify` skill's `references/feature-map.md`, in the same PR. Then follow the
57
+ `verify` skill's "Check a change" for that feature. Replace the whole report in the PR body with the
58
+ new output of `bun verify report --human`.
59
+
60
+ ## Upgrade the template
61
+
62
+ When `lint` reports that the skill follows an older template:
63
+
64
+ 1. Run `bunx @wringer/gunshi skill install`, as [Install the skill](../SKILL.md#install-the-skill)
65
+ shows. It replaces the repo's copy of the wringer skill.
66
+ 2. Move the repo's `verify` skill folder, such as `.claude/skills/verify/`, to a folder outside
67
+ `.claude/skills/`, so it doesn't load as a second skill. List that folder in `.git/info/exclude`,
68
+ so git ignores it without a change to `.gitignore`.
69
+ 3. Copy `.claude/skills/wringer/template/verify/` to the folder that `runVerify`'s `skill` option
70
+ names, which no longer exists.
71
+ 4. Copy the old skill's `references/feature-map.md` over the template's. Copy the frontmatter's
72
+ `name`, `description` and `metadata.wringer-command`, the `#` title, and each `<!-- repo -->`
73
+ block, from the old `SKILL.md` into the new one. When the new template renames or adds a block,
74
+ fill it from the old skill's matching content.
75
+ 5. Read the release notes of each `@wringer/gunshi` version since the old one on
76
+ <https://github.com/zgeoff/wringer/releases>. Apply what they ask of the `<!-- repo -->` blocks,
77
+ `verify.ts` and the registry.
78
+ 6. Run `bun verify lint`. Expect: `ok: true`. Then delete the old skill.
@@ -0,0 +1,42 @@
1
+ # Prove
2
+
3
+ Prove that the verify CLI, its registry and the repo's `verify` skill work before you open the PR
4
+ that adds them.
5
+
6
+ - Make every change to the code, the registry and the `verify` skill before step 2. A verdict holds
7
+ for the code as it was at `done`: an edit makes it stale, and undoing the edit makes it hold
8
+ again.
9
+ - When a fresh subagent names a gap, follow the brief. When another step fails because the `verify`
10
+ skill, the registry or the CLI code is wrong, fix it, and start again at step 1.
11
+ - For each step, put its command and the output lines its "Expect" lists in the PR description,
12
+ under `## Verification`. Add the heading when the PR template lacks it.
13
+
14
+ ## Steps
15
+
16
+ 1. Run `bun verify up`, then `bun verify doctor`. Expect: the doctor's last JSON line has `ok: true`
17
+ and `data.passed: true`. Then run `bun verify down`.
18
+ 2. Send the [fresh subagent brief](./fresh-subagent-brief.md) to a new subagent, and follow that
19
+ reference until one subagent reaches `done` on every feature and names no gap. Expect: its reply,
20
+ with exit code 0 from each `done`. Put the subagent's result for each `done` in the PR: the
21
+ feature, the exit code, `ok` and `data.fingerprint`.
22
+ 3. Check that the CLI refuses to run against a changed tree:
23
+ 1. Run `bun verify up`, then `bun verify doctor`. Expect: `data.passed: true`.
24
+ 2. Add a blank line to a file that a feature's `paths` globs match.
25
+ 3. From that feature's journey in the `verify` skill's feature map, run one command that touches
26
+ the app, such as an `action` or a `browser` command. Expect: exit code 3 and `error.code`
27
+ `doctor-required`.
28
+ 4. Undo the edit, and run `bun verify down`.
29
+ 4. When the Targets section of the `verify` skill lists a read-only target, check that it refuses a
30
+ write. Skip this step when it lists none.
31
+ 1. Start the instance the target attaches to, as the skill says. Use an instance you may lose
32
+ data on, in case the refusal is broken.
33
+ 2. Run `bun verify use --target <target>`, then `bun verify attach`, then `bun verify doctor`.
34
+ 3. Run one command that `--help` marks `[write]`, such as a write action. Expect: exit code 3 and
35
+ `error.code` `read-only`.
36
+ 4. Run `bun verify detach`, then `bun verify use --target local`.
37
+ 5. Run `bun verify report --human`. Expect: each feature whose `paths` match a file the branch
38
+ changes shows `verified`, every other feature shows `unchanged`, and the report lists no changed
39
+ path under "Changed paths that no feature maps". When it lists one, add the path to a feature's
40
+ `paths`, or to the registry's `.ignore` list when the running app never reads it. Then start
41
+ again at step 1. Paste the whole output into the PR description as it is, outside a code block.
42
+ The gate reads the report from the HTML comment at its end.