@wringer/gunshi 0.2.0 → 0.3.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 (62) hide show
  1. package/README.md +25 -24
  2. package/dist/build-cli-wringer.d.ts +2 -0
  3. package/dist/build-guide-command.d.ts +2 -0
  4. package/dist/build-guide-ports.d.ts +4 -0
  5. package/dist/build-guide-wringer.d.ts +2 -0
  6. package/dist/build-lint-command.d.ts +1 -1
  7. package/dist/check-feature-file.d.ts +5 -0
  8. package/dist/collect-dead-globs.d.ts +3 -3
  9. package/dist/collect-unclaimed-files.d.ts +2 -0
  10. package/dist/parse-feature-table-span.d.ts +11 -0
  11. package/dist/parse-guide-topic.d.ts +6 -0
  12. package/dist/parse-skill-metadata.d.ts +1 -1
  13. package/dist/pick-guide-data.d.ts +20 -0
  14. package/dist/read-guide.d.ts +3 -0
  15. package/dist/read-template-hash.d.ts +1 -0
  16. package/dist/resolve-lint-failures.d.ts +6 -1
  17. package/dist/run-cli.d.ts +3 -1
  18. package/dist/run-verify.d.ts +3 -0
  19. package/dist/scrub-parsed-invocation.d.ts +3 -0
  20. package/{skills/wringer/references → guide}/create.md +29 -25
  21. package/{skills/wringer/references → guide}/fresh-subagent-brief.md +2 -0
  22. package/{skills/wringer/references → guide}/maintain.md +29 -22
  23. package/guide/overview.md +135 -0
  24. package/{skills/wringer/references → guide}/prove.md +16 -13
  25. package/guide/template/verify/SKILL.md +172 -0
  26. package/guide/template/verify/references/feature-add-item.md +20 -0
  27. package/{skills/wringer → guide}/template/verify-registry.ts +2 -1
  28. package/package.json +10 -9
  29. package/src/build-cli-wringer.ts +32 -0
  30. package/src/build-guide-command.ts +37 -0
  31. package/src/build-guide-ports.ts +73 -0
  32. package/src/build-guide-wringer.ts +19 -0
  33. package/src/build-lint-command.ts +32 -6
  34. package/src/check-feature-file.ts +105 -0
  35. package/src/collect-dead-globs.ts +18 -11
  36. package/src/collect-unclaimed-files.ts +17 -0
  37. package/src/parse-feature-table-span.ts +56 -0
  38. package/src/parse-guide-topic.ts +14 -0
  39. package/src/parse-skill-metadata.ts +8 -6
  40. package/src/pick-guide-data.ts +47 -0
  41. package/src/read-guide.ts +49 -0
  42. package/src/read-template-hash.ts +42 -0
  43. package/src/render-human-envelope.ts +7 -0
  44. package/src/resolve-lint-failures.ts +182 -11
  45. package/src/run-cli.ts +17 -2
  46. package/src/run-verify.ts +38 -15
  47. package/src/scrub-parsed-invocation.ts +32 -0
  48. package/src/wringer-gunshi.ts +7 -24
  49. package/dist/build-linted-wringer.d.ts +0 -2
  50. package/dist/find-skill-copy-refusal.d.ts +0 -8
  51. package/dist/parse-skill-install-args.d.ts +0 -3
  52. package/dist/template-version.d.ts +0 -1
  53. package/dist/write-skill-copy.d.ts +0 -12
  54. package/skills/wringer/SKILL.md +0 -143
  55. package/skills/wringer/template/verify/SKILL.md +0 -176
  56. package/skills/wringer/template/verify/references/feature-map.md +0 -17
  57. package/src/build-linted-wringer.ts +0 -16
  58. package/src/find-skill-copy-refusal.ts +0 -34
  59. package/src/parse-skill-install-args.ts +0 -25
  60. package/src/template-version.ts +0 -3
  61. package/src/write-skill-copy.ts +0 -75
  62. /package/{skills/wringer → guide}/template/verify.ts +0 -0
package/README.md CHANGED
@@ -39,41 +39,42 @@ does on any duplicate name.
39
39
  Markdown that tells the repo's agents how to use each feature. `lint` reads that folder. The path
40
40
  defaults to `.claude/skills/verify`.
41
41
 
42
- ## Agent skill
42
+ ## Guide
43
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.
44
+ The package ships a guide in `guide/`. It walks an agent through adding a verify CLI, a feature map
45
+ and a verify skill to a repo, and through the checks that prove them. Its `template/` folder holds
46
+ the example files for the repo's own verify skill, which the agent writes.
47
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:
48
+ The CLI prints the guide of the installed version, so no copy in the repo goes stale:
50
49
 
51
50
  ```bash
52
- bunx @wringer/gunshi skill install
51
+ bun verify guide # the version and the topics
52
+ bun verify guide create # one topic
53
+ bunx wringer-gunshi guide # the same, for a repo that has no verify CLI yet
53
54
  ```
54
55
 
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.
56
+ An unknown topic fails with `usage`, and its hint lists the topics. `guide template` prints the
57
+ absolute path of the installed template folder, to copy from. `--human` prints a topic's text alone.
57
58
 
58
59
  ## lint
59
60
 
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.
61
+ `bun verify.ts lint` checks the features and the verify skill with no running app, so CI can run it
62
+ on a fresh checkout. It exits with code 1 and `check-failed` on any of these:
63
+
64
+ - a feature, `.shared()` or `.ignore()` glob that matches no file, or a file that no such glob
65
+ matches;
66
+ - a missing or orphaned `references/feature-<name>.md`, or a feature file without `## Journey` and
67
+ `## End state` or whose first `bash` line is not `<cli> use --feature <name>`;
68
+ - a `SKILL.md` feature table, between the `wringer:features` markers, that differs from
69
+ `features --markdown`;
70
+ - a registry file that no `.shared()` or feature `paths` glob matches;
71
+ - a line in a fenced code block of the skill's Markdown files that calls the CLI and fails to parse,
72
+ fails the command's schema, or names a feature or target the registry lacks;
73
+ - a missing `SKILL.md`, a frontmatter without `metadata.wringer-template` or
74
+ `metadata.wringer-command`, or another template hash. The `maintain` guide topic upgrades it.
73
75
 
74
76
  `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.
77
+ only code block lines that start with them, after an optional `$ ` prompt and assignments.
77
78
 
78
79
  ## Behaviour
79
80
 
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function buildCLIWringer(wringer: Wringer, skillFolder: string, registryFile?: string | null): Wringer;
@@ -0,0 +1,2 @@
1
+ import type { RegisteredCommand } from '@wringer/core';
2
+ export declare function buildGuideCommand(): RegisteredCommand;
@@ -0,0 +1,4 @@
1
+ import type { CLIPorts } from './run-cli.ts';
2
+ type RepoPorts = Pick<CLIPorts, 'readRepoRoot' | 'openRepo'>;
3
+ export declare function buildGuidePorts(selfCommand: readonly string[]): RepoPorts;
4
+ export {};
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function buildGuideWringer(): Wringer;
@@ -1,2 +1,2 @@
1
1
  import type { RegisteredCommand } from '@wringer/core';
2
- export declare function buildLintCommand(skillFolder: string): RegisteredCommand;
2
+ export declare function buildLintCommand(skillFolder: string, registryFile: string | null): RegisteredCommand;
@@ -0,0 +1,5 @@
1
+ export interface FeatureFileProblem {
2
+ readonly line: number;
3
+ readonly problem: string;
4
+ }
5
+ export declare function checkFeatureFile(text: string, name: string, cliWords: readonly string[] | null): readonly FeatureFileProblem[];
@@ -1,6 +1,6 @@
1
- import type { FeatureDefinition } from '@wringer/core';
1
+ import type { Wringer } from '@wringer/core';
2
2
  export interface DeadGlob {
3
- readonly feature: string;
3
+ readonly where: string;
4
4
  readonly glob: string;
5
5
  }
6
- export declare function collectDeadGlobs(features: readonly FeatureDefinition[], files: readonly string[]): readonly DeadGlob[];
6
+ export declare function collectDeadGlobs(wringer: Wringer, files: readonly string[]): readonly DeadGlob[];
@@ -0,0 +1,2 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ export declare function collectUnclaimedFiles(wringer: Wringer, files: readonly string[]): readonly string[];
@@ -0,0 +1,11 @@
1
+ export type FeatureTableSpan = {
2
+ readonly ok: true;
3
+ readonly line: number;
4
+ readonly table: string;
5
+ } | {
6
+ readonly ok: false;
7
+ readonly line: number;
8
+ readonly reason: string;
9
+ };
10
+ export declare function parseFeatureTableSpan(text: string): FeatureTableSpan;
11
+ export declare function toComparableTable(table: string): string;
@@ -0,0 +1,6 @@
1
+ export interface GuideTopic {
2
+ readonly name: string;
3
+ readonly summary: string;
4
+ readonly text: string;
5
+ }
6
+ export declare function parseGuideTopic(name: string, text: string): GuideTopic;
@@ -1,6 +1,6 @@
1
1
  export type SkillMetadata = {
2
2
  readonly ok: true;
3
- readonly templateVersion: number;
3
+ readonly template: string | number;
4
4
  readonly cliWords: readonly string[];
5
5
  } | {
6
6
  readonly ok: false;
@@ -0,0 +1,20 @@
1
+ import { WringerError } from '@wringer/core';
2
+ import { z } from 'zod';
3
+ import type { GuideTopic } from './parse-guide-topic.ts';
4
+ export declare const guideDataSchema: z.ZodUnion<readonly [z.ZodObject<{
5
+ version: z.ZodString;
6
+ topics: z.ZodArray<z.ZodObject<{
7
+ name: z.ZodString;
8
+ summary: z.ZodString;
9
+ }, z.core.$strict>>;
10
+ }, z.core.$strict>, z.ZodObject<{
11
+ version: z.ZodString;
12
+ topic: z.ZodString;
13
+ text: z.ZodString;
14
+ }, z.core.$strict>]>;
15
+ export type GuideData = z.infer<typeof guideDataSchema>;
16
+ export interface Guide {
17
+ readonly version: string;
18
+ readonly topics: readonly GuideTopic[];
19
+ }
20
+ export declare function pickGuideData(guide: Guide, topic: string | undefined): GuideData | WringerError;
@@ -0,0 +1,3 @@
1
+ import type { Guide } from './pick-guide-data.ts';
2
+ export declare const guideFolder: string;
3
+ export declare function readGuide(folder?: string): Promise<Guide>;
@@ -0,0 +1 @@
1
+ export declare function readTemplateHash(folder?: string): Promise<string>;
@@ -3,9 +3,13 @@ import { z } from 'zod';
3
3
  import type { MarkdownFile } from './collect-journey-commands.ts';
4
4
  export declare const lintFailureSchema: z.ZodObject<{
5
5
  check: z.ZodEnum<{
6
+ "feature-file": "feature-file";
7
+ "feature-table": "feature-table";
6
8
  journey: "journey";
7
9
  paths: "paths";
10
+ registry: "registry";
8
11
  template: "template";
12
+ unclaimed: "unclaimed";
9
13
  }>;
10
14
  where: z.ZodString;
11
15
  problem: z.ZodString;
@@ -15,8 +19,9 @@ export interface LintInput {
15
19
  readonly wringer: Wringer;
16
20
  readonly files: readonly string[];
17
21
  readonly skillPath: string;
22
+ readonly registryFile: string | null;
18
23
  readonly skillFiles: readonly MarkdownFile[];
19
- readonly templateVersion: number;
24
+ readonly templateHash: string;
20
25
  }
21
26
  export interface LintResult {
22
27
  readonly commands: number;
package/dist/run-cli.d.ts CHANGED
@@ -1,7 +1,8 @@
1
- import type { RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
1
+ import type { PullRequestHost, RepoHost, StatePort, SupervisorPort, Wringer, WringerError } from '@wringer/core';
2
2
  interface RepoPorts {
3
3
  readonly state: StatePort;
4
4
  readonly repoHost: RepoHost;
5
+ readonly pullRequests: PullRequestHost;
5
6
  readonly supervisor: SupervisorPort;
6
7
  }
7
8
  export interface CLIPorts {
@@ -9,6 +10,7 @@ export interface CLIPorts {
9
10
  readonly cwd: string;
10
11
  readonly isTTY: boolean;
11
12
  readonly isAgent: boolean;
13
+ readonly env: Readonly<Record<string, string | undefined>>;
12
14
  readonly writeStdout: (text: string) => void;
13
15
  readonly readRepoRoot: (cwd: string) => Promise<string | WringerError>;
14
16
  readonly openRepo: (root: string) => RepoPorts;
@@ -1,5 +1,8 @@
1
1
  import type { Wringer } from '@wringer/core';
2
+ import type { CLIPorts } from './run-cli.ts';
2
3
  export interface VerifyOptions {
3
4
  readonly skill?: string | undefined;
5
+ readonly registry?: string | undefined;
4
6
  }
5
7
  export declare function runVerify(wringer: Wringer, options?: VerifyOptions): Promise<void>;
8
+ export declare function runWringer(wringer: Wringer, repoPorts?: Pick<CLIPorts, 'readRepoRoot' | 'openRepo'>): Promise<void>;
@@ -0,0 +1,3 @@
1
+ import type { Wringer } from '@wringer/core';
2
+ import type { ParsedInvocation } from './pick-cli-outcome.ts';
3
+ export declare function scrubParsedInvocation(parsed: ParsedInvocation, wringer: Wringer, env: Readonly<Record<string, string | undefined>>): ParsedInvocation;
@@ -1,9 +1,11 @@
1
1
  # Create
2
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.
3
+ Write the verify CLI, its registry and the repo's verify skill
4
+
5
+ Add the verify CLI, its
6
+ [registry](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md#registry) and the
7
+ repo's `verify` skill. `verify-registry.ts` in the template shows one target, driver, action, repo
8
+ command, doctor check and feature, on the builder that `createWringer` returns.
7
9
 
8
10
  The mistakes that cost the most:
9
11
 
@@ -26,21 +28,21 @@ The mistakes that cost the most:
26
28
  1. Install each driver the app needs, at an exact version, such as
27
29
  `bun add --dev --exact @wringer/http`. Expect: each one in `devDependencies`.
28
30
 
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 |
31
+ | Driver | Drives |
32
+ | ------------------- | -------------------------------------------- |
33
+ | `@wringer/browser` | a page, through its accessibility tree |
34
+ | `@wringer/http` | the app's HTTP API |
35
+ | `@wringer/db` | SQL on the app's SQLite or Postgres database |
36
+ | `@wringer/stream` | the app's logs, recorded for the whole run |
37
+ | `@wringer/terminal` | a text program, through its screen |
35
38
 
36
39
  Each driver adds its own commands and its own doctor check. Its README in `node_modules/` gives
37
40
  its config for a target.
38
41
 
39
42
  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.
43
+ 3. Copy `verify.ts` and `verify-registry.ts` from the template (`bun verify guide template` names
44
+ its folder) into `scripts/verify/`. Add `"verify": "bun scripts/verify/verify.ts"` to the
45
+ `scripts` of `package.json`. Expect: `bun verify --help` lists the template's commands.
44
46
  4. In `verify-registry.ts`, write the `local` target with `mode: 'launch'` and
45
47
  `access: 'read-write'`. Its `launch` function returns:
46
48
  - `command`: the command a developer runs to start the app;
@@ -66,23 +68,25 @@ The mistakes that cost the most:
66
68
  of the files that change its behaviour.
67
69
  11. The gate fails a PR that changes a file matched by neither a feature's `paths` nor an ignore
68
70
  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:
71
+ `**/*.md`, `**/*.test.ts`, `.github/**` and `.claude/**`. Add each other file to the `paths` of
72
+ each feature whose behaviour it changes: a file such as `package.json` changes every feature.
73
+ Call `.shared` with the globs of the files that change every feature, such as the registry's own
74
+ folder, because `lint` fails a registry file that no shared glob or `paths` glob matches.
75
+ Expect: each file that `git ls-files` prints matches a feature's `paths` or an ignore glob.
76
+ 12. Copy `verify/` from the template to `.claude/skills/verify/`. Rewrite the frontmatter's `name`
77
+ and `description` and the `#` title for the app. Set `metadata.wringer-command` to the command
78
+ that runs the script, `bun verify` by default. Rewrite each `<!-- repo: <part> -->` block:
77
79
  - `targets`: one row per target, with the command that starts a run, and what to do on a
78
80
  refusal.
79
81
  - `commands`: what `--help` can't say about the actions and repo commands, such as the order to
80
82
  run them in.
81
83
  - `registry`: the path of the registry file.
82
84
 
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.
85
+ Then delete `references/feature-add-item.md` and write one `references/feature-<name>.md` per
86
+ feature, in the template's form: what it does, how a user reaches it, a `## Journey` section
87
+ whose first `bash` block starts with `bun verify use --feature <name>` and runs as written, and
88
+ a `## End state` section. Replace the feature table between the `wringer:features` markers with
89
+ the output of `bun verify features --markdown`.
86
90
 
87
91
  13. Run `bun verify lint`. Expect: `ok: true`, and `data.commands`, the count of journey lines it
88
92
  parsed, above 0. A count of 0 means it found no journey.
@@ -1,5 +1,7 @@
1
1
  # Fresh subagent brief
2
2
 
3
+ The brief to send a fresh subagent that tries the verify skill
4
+
3
5
  Send the brief below to a new general-purpose subagent. Never use a fork: a fork carries your
4
6
  context, and the subagent must know only what the repo's `verify` skill tells it. Fill in the three
5
7
  placeholders, and add nothing else. A fact you add about the app or the CLI hides a gap in the
@@ -1,5 +1,7 @@
1
1
  # Maintain
2
2
 
3
+ Keep the gate, lint and the journeys true, and upgrade the verify skill
4
+
3
5
  Wire `bun verify lint` and the gate into the repo's CI, fix a journey when its feature changes, and
4
6
  upgrade the `verify` skill when `lint` reports an older template.
5
7
 
@@ -8,11 +10,9 @@ The mistakes that cost the most:
8
10
  - **A shallow checkout.** The gate needs the merge base with the PR's base branch, so it fails on a
9
11
  checkout without the full history.
10
12
  - **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.
13
+ `edited` event misses a report that `bun verify publish` writes later.
12
14
  - **A nested copy.** `cp -R` into a folder that exists nests the copy inside it. Move the old
13
15
  `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
16
 
17
17
  ## Wire the checks into CI
18
18
 
@@ -20,7 +20,7 @@ The mistakes that cost the most:
20
20
  run in any job that has the repo's dependencies. The gate reads the last report block in the PR body
21
21
  and works out the code's fingerprint itself. It fails with exit code 1 in two cases:
22
22
 
23
- - A changed feature has no verdict, or a verdict for other code.
23
+ - A changed feature has no verdict, or a verdict for other code in its own files or a shared path.
24
24
  - A changed file matches neither a feature's `paths` nor a glob in the ignore list, which the
25
25
  registry sets with `.ignore`. `bun verify gate` lists each such file in `data.unmapped`. When the
26
26
  running app never reads the file, add it to the ignore list. Otherwise add it to a feature's
@@ -53,26 +53,33 @@ Keep it a workflow of its own, so a body edit reruns only this job.
53
53
 
54
54
  A journey breaks when a change to its feature, such as a renamed button, makes a command of its
55
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`.
56
+ journey in the feature's `references/feature-<name>.md` in the `verify` skill, in the same PR. Then
57
+ follow the `verify` skill's "Check a change" for that feature. Run `bun verify publish` to replace
58
+ the report in the PR description.
59
59
 
60
60
  ## Upgrade the template
61
61
 
62
- When `lint` reports that the skill follows an older template:
62
+ Upgrade the repo's `verify` skill when `lint` fails with check `template`. The check fails when the
63
+ skill's `metadata.wringer-template` holds a version number, or a hash other than the hash of the
64
+ installed template.
63
65
 
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`,
66
+ 1. Run `bun verify guide template`. It names the folder of the template that the installed
67
+ `@wringer/gunshi` ships.
68
+ 2. Move the repo's `verify` skill folder to a folder outside `.claude/skills/`, so it doesn't load
69
+ as a second skill. The skill folder is the path that the `skill` option of `runVerify` in
70
+ `verify.ts` names, such as `.claude/skills/verify/`. List the new folder in `.git/info/exclude`,
68
71
  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.
72
+ 3. Copy the template's `verify/` folder to the skill folder path, which step 2 emptied.
73
+ 4. Delete the new skill's `references/feature-add-item.md`, the template's example feature, which
74
+ fails `lint` unless the repo has a feature of that name. Copy the old skill's
75
+ `references/feature-*.md` files into the new skill's `references/`.
76
+ 5. In the new `SKILL.md`, replace the feature table between the `wringer:features` markers with the
77
+ output of `bun verify features --markdown`.
78
+ 6. Copy the frontmatter's `name`, `description` and `metadata.wringer-command` from the old
79
+ `SKILL.md` into the new one. Copy the `#` title and each `<!-- repo -->` block too. When the new
80
+ template renames or adds a block, fill it from the old skill's matching content.
81
+ 7. In the lockfile's git history, find the `@wringer/gunshi` version from before the bump. Read the
82
+ release notes of each later version on <https://github.com/zgeoff/wringer/releases>. Apply what
83
+ they ask of the `<!-- repo -->` blocks, `verify.ts` and the registry.
84
+ 8. Run `bun verify lint`. Expect: `ok: true`. Then delete the old skill and its line in
85
+ `.git/info/exclude`.
@@ -0,0 +1,135 @@
1
+ # Build a verify CLI with wringer
2
+
3
+ What a verify CLI is, and the steps to add one to a repo and keep it true
4
+
5
+ Give the repo's agents one way to use its real app and keep the evidence of what they checked. Build
6
+ these in the repo:
7
+
8
+ - a verify CLI on the `@wringer/*` packages, which an agent runs as `bun verify <command>`;
9
+ - its [registry](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md#registry), with
10
+ each feature's `paths` globs and the ignore list set with `.ignore`;
11
+ - a `verify` skill, with a feature file for each feature, `references/feature-<name>.md`, that gives
12
+ its journey and end state.
13
+
14
+ The [terms page](https://github.com/zgeoff/wringer/blob/main/docs/reference/terms.md) defines each
15
+ word this guide uses: registry, target, driver, action, command, feature, journey, run, doctor,
16
+ verdict, fingerprint, evidence, report, gate, shared glob and ignore list.
17
+
18
+ Then prove that the CLI, the registry and the skill work, and wire the checks that keep them true.
19
+ Hand back the PR that adds them, with the proof in its description. The mistakes that cost the most:
20
+
21
+ - **Calling the work done before a fresh agent uses the skill.** You know the app; the repo's next
22
+ agent knows only the `verify` skill. Run a subagent with none of your context to show that the
23
+ skill works.
24
+ - **Copying commands into the `verify` skill.** The CLI lists its own commands in `--help`, and a
25
+ copy goes stale. Point at `--help`, and write only what the help can't say.
26
+ - **A `paths` glob that matches no file.** The gate then fails on each file the glob should cover,
27
+ and lists it as unmapped. A file that another feature's glob covers passes. Run `bun verify lint`
28
+ to find such a glob.
29
+ - **Writing a repo's own choices outside the `<!-- repo -->` blocks of the `verify` skill.** An
30
+ upgrade of the template replaces every line outside them. Put each choice, such as where an agent
31
+ reports a refused write, in a block or in the repo's code.
32
+
33
+ ## Key rules
34
+
35
+ - [Topics](#topics): `guide <topic>` prints the commands for each step.
36
+ - [Install](#install): add the packages, then read this guide from the CLI at the version the repo
37
+ installs.
38
+ - [The template](#the-template): the files to copy, with fixed parts and repo parts.
39
+ - [Create](#create): read the repo, then write the CLI, the actions, the checks, 3 to 5 features,
40
+ the ignore list and the `verify` skill.
41
+ - [Prove](#prove): doctor passes, a fresh subagent reaches `done` on every feature, the CLI refuses
42
+ a command before the doctor passes and a write on a read-only target, and `bun verify publish`
43
+ writes the report into the PR.
44
+ - [Maintain](#maintain): the gate and `lint` in CI, and a template upgrade when `lint` asks.
45
+
46
+ ## Topics
47
+
48
+ Run `bunx wringer-gunshi guide <topic>` in a repo with no verify CLI yet, or
49
+ `bun verify guide <topic>` in one that has it. Each prints the guide of the installed
50
+ `@wringer/gunshi`, so it matches the packages the repo runs.
51
+
52
+ - `create`: writing the CLI, the registry and the `verify` skill in a repo.
53
+ - `prove`: the proof steps and what each shows in the PR.
54
+ - `fresh-subagent-brief`: the brief to give the subagent in the prove flow.
55
+ - `maintain`: wiring the gate and `lint` into CI, and upgrading the template.
56
+ - `template`: where the template files are, to copy from.
57
+
58
+ ## Install
59
+
60
+ ```bash
61
+ bun add --dev --exact @wringer/core @wringer/gunshi zod
62
+ bunx wringer-gunshi guide
63
+ ```
64
+
65
+ The second command lists the topics. Read the guide again after each upgrade of `@wringer/gunshi`.
66
+
67
+ The CLI runs on Bun. When the repo installs packages with another package manager, use it for
68
+ `bun add` and `bunx`, such as `pnpm add` and `pnpm dlx`. Also use it in the `verify` skill's
69
+ `metadata.wringer-command`, such as `pnpm verify`. The `verify` script in `package.json` still runs
70
+ the CLI with `bun`.
71
+
72
+ ## The template
73
+
74
+ `bun verify guide template`, or `bunx wringer-gunshi guide template` before the repo has a verify
75
+ CLI, prints the absolute path of the installed template folder. It holds a working example for an
76
+ invented app, Larder:
77
+
78
+ | File | Copy to | Holds |
79
+ | -------------------- | ----------------------------------- | ----------------------------------------------------------------- |
80
+ | `verify.ts` | `scripts/verify/verify.ts` | the entry point that calls `runVerify` |
81
+ | `verify-registry.ts` | `scripts/verify/verify-registry.ts` | targets, a driver, an action, a command, a check, a feature |
82
+ | `verify/` | `.claude/skills/verify/` | the repo's `verify` skill, and its feature files in `references/` |
83
+
84
+ Skip `verify-registry.test.ts` in the template: it tests the template inside wringer.
85
+
86
+ These locations are defaults. When you change one, change each place that refers to it:
87
+
88
+ - the folder `scripts/verify/`:
89
+ - the `verify` script's path in `package.json`;
90
+ - its glob in the registry's `.shared` list;
91
+ - the `registry` option of `runVerify`, when the registry lives apart from `verify.ts`;
92
+ - the skill folder: `runVerify`'s `skill` option, a path from the repo root;
93
+ - the script name `verify`: the `package.json` script and the skill's `metadata.wringer-command`,
94
+ such as `bun verify`.
95
+
96
+ In the `verify` skill's `SKILL.md`, each `<!-- repo: <part> -->` block ends at `<!-- /repo -->` and
97
+ holds what only this repo knows. Rewrite those blocks, the frontmatter's `name` and `description`,
98
+ and the `#` title. Keep every other line. The repo owns each `references/feature-*.md` whole. Keep
99
+ `metadata.wringer-template` as the template has it. `lint` compares that value with the hash of the
100
+ template that the installed `@wringer/gunshi` ships. The `maintain` topic's upgrade copies in the
101
+ new value.
102
+
103
+ ## Create
104
+
105
+ Read how the app starts, what it prints when it is ready, and which state it keeps. Then follow the
106
+ `create` topic: it ends with 3 to 5 features in the registry, each with a journey in the `verify`
107
+ skill, an ignore list for the files with no runtime effect, and `bun verify lint` passing.
108
+
109
+ ## Prove
110
+
111
+ The work is done only when each of these holds. The `prove` topic gives the commands.
112
+
113
+ 1. `bun verify doctor` passes on `local`.
114
+ 2. A fresh subagent that loads only the new `verify` skill reaches `done` on every feature. New
115
+ feature files need one pass by an agent who did not write it, and this run is that pass.
116
+ 3. After an edit to a file that a feature's `paths` match, a command that touches the app fails with
117
+ `doctor-required`. On a read-only target, if the repo has one, try one write: the CLI refuses it
118
+ with `read-only`.
119
+ 4. `bun verify publish` has written the report into the description of the PR that adds the CLI. The
120
+ gate reads the report from the HTML comment at the report's end.
121
+
122
+ ## Maintain
123
+
124
+ Keep these in place, as the `maintain` topic shows:
125
+
126
+ - **The gate on each PR.** A PR that touches a feature's `paths` needs a verdict that the agent
127
+ recorded with `bun verify done` on the PR's latest code. A PR that touches a file outside every
128
+ feature's `paths` and the ignore list fails until you add the file to one of them.
129
+ - **`lint` in CI.** It needs no running app. When it reports another template hash, upgrade the
130
+ template as the `maintain` topic says.
131
+ - **A journey fixed with its feature.** A PR that changes a feature updates the feature's journey.
132
+
133
+ Don't add a scheduled job. The gate checks a feature each time a PR changes it.
134
+
135
+ **Reply:** the PR link, and for each prove step, the command and the output lines that show it held.
@@ -1,7 +1,9 @@
1
1
  # Prove
2
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.
3
+ Prove the verify CLI, its registry and its skill work before the PR
4
+
5
+ Prove that the verify CLI, its registry and the repo's `verify` skill work before you ask for review
6
+ of the PR that adds them.
5
7
 
6
8
  - Make every change to the code, the registry and the `verify` skill before step 2. A verdict holds
7
9
  for the code as it was at `done`: an edit makes it stale, and undoing the edit makes it hold
@@ -15,14 +17,14 @@ that adds them.
15
17
 
16
18
  1. Run `bun verify up`, then `bun verify doctor`. Expect: the doctor's last JSON line has `ok: true`
17
19
  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`.
20
+ 2. Send the brief of `guide fresh-subagent-brief` to a new subagent, and follow that reference until
21
+ one subagent reaches `done` on every feature and names no gap. Expect: its reply, with exit code
22
+ 0 from each `done`. Put the subagent's result for each `done` in the PR: the feature, the exit
23
+ code, `ok` and `data.fingerprint`.
22
24
  3. Check that the CLI refuses to run against a changed tree:
23
25
  1. Run `bun verify up`, then `bun verify doctor`. Expect: `data.passed: true`.
24
26
  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
27
+ 3. From that feature's journey in the `verify` skill's feature file, run one command that touches
26
28
  the app, such as an `action` or a `browser` command. Expect: exit code 3 and `error.code`
27
29
  `doctor-required`.
28
30
  4. Undo the edit, and run `bun verify down`.
@@ -34,9 +36,10 @@ that adds them.
34
36
  3. Run one command that `--help` marks `[write]`, such as a write action. Expect: exit code 3 and
35
37
  `error.code` `read-only`.
36
38
  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.
39
+ 5. Run `bun verify report --human` to read the report locally. Expect: each feature whose `paths`
40
+ match a file the branch changes shows `verified`, every other feature shows `unchanged`, and the
41
+ report lists no changed path under "Changed paths that no feature maps". When it lists one, add
42
+ the path to a feature's `paths`, or to the registry's `.ignore` list when the running app never
43
+ reads it. Then start again at step 1. Otherwise push the branch and open its PR. Then run
44
+ `bun verify publish`. Expect: `ok: true`. It writes the report into the PR description, and the
45
+ gate reads the report from the HTML comment at the report's end.