vibeqm-check 0.4.3 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -38,8 +38,8 @@ answers to both names.
38
38
  - **It sends nothing to us.** There is no account, no telemetry and no server of ours
39
39
  involved: the checks run on your machine, and the report is printed there.
40
40
  - **The one outside call is optional and yours.** If the GitHub CLI (`gh`) is logged
41
- in, the tool asks GitHub, with your own login, for this repository's CI runs and
42
- merged pull requests, read-only, to see checks that failed and reviews that
41
+ in, the tool asks GitHub, with your own login, for this repository's CI runs,
42
+ merged pull requests and branch rules, read-only, to see checks that failed, reviews that
43
43
  happened. `--offline` turns that off.
44
44
  - The AI prompt it prints goes nowhere by itself; you decide whether to give it to
45
45
  your coding agent.
@@ -50,28 +50,42 @@ Inside an AI coding agent, run it as a shell command (in Claude Code:
50
50
  ## Start from the templates
51
51
 
52
52
  `npx vibeqm-check init` creates the files a repository needs for Level 2: a rules file
53
- for AI agents (`AGENTS.md`), agent permissions, a CI workflow with secret scanning
54
- and static security analysis, issue and pull request templates, and short
55
- requirements, decisions and plan files under `VibeQM/`. It shows the list first,
56
- skips files that already exist, and writes only after you say yes (`--yes` when not
57
- run in a terminal). Fill every `<...>` with your repository's facts: the checks don't
58
- count a file that still has them. The templates come from the
53
+ for AI agents (`AGENTS.md`), agent permissions, a blocking pre-commit hook
54
+ (`.githooks/pre-commit`, enabled with `git config core.hooksPath .githooks`), a CI
55
+ workflow with secret scanning and static security analysis, issue and pull request
56
+ templates, and short requirements, decisions and plan files under `VibeQM/`. It
57
+ shows the list first, skips files that already exist, and writes only after you say
58
+ yes (`--yes` when not run in a terminal). The blanks your repository answers (the
59
+ test and build commands, the description) are filled; fill the rest of the `<...>`
60
+ with your repository's facts, or let your agent do it. The checks don't count a file
61
+ that still has blanks. The templates come from the
59
62
  [companion repository](https://github.com/vibeqm/vqm).
60
63
 
61
64
  ## What you get
62
65
 
63
66
  - **The level** your repository's evidence supports, Level 1 to 3. Levels 4 and 5
64
67
  need measurements over time, which this version does not yet compute.
65
- - **Every check, with one of three results:**
68
+ - **How far the next level is, and who does what.** The result leads with the
69
+ distance ("Level 2 is 4 items away"), what is already met, how many of the open
70
+ items your AI agent can do alone and how many need an answer from you, today's
71
+ level, and the autonomy the next level earns.
72
+ - **Every check, with one of four results:**
66
73
  - **Met:** the evidence exists, and the report names it (a file, a setting, a hook,
67
74
  a commit).
68
75
  - **Not met:** the tool looked and the evidence is absent.
69
76
  - **Not visible:** the evidence lives outside the repository (for example settings
70
- on your code host). It counts as not met until a person attaches proof.
77
+ on your code host). It counts as not met until a person attaches proof. With the
78
+ GitHub CLI logged in, the tool reads branch protection and required checks
79
+ itself.
80
+ - **In place:** the practice is set up and recorded but counts with use (peer
81
+ review counts after 20 reviewed changes; one unreviewed push restarts the count).
82
+ The result shows the count, so you see when it will be met.
71
83
  - **For every open check:** why it matters, concrete steps for this repository, how to
72
- confirm it worked, and an estimate in minutes.
84
+ confirm it worked, an estimate in minutes, and who it needs: your agent alone, an
85
+ answer from you, a setting on the code host, or use.
73
86
  - **A prompt** at the end that your AI coding agent can follow to close the gaps,
74
- cheapest first. The prompt tells the agent to produce real evidence, and to ask you
87
+ cheapest first. The prompt tells the agent to do everything it can alone first and
88
+ then ask you for the rest in one message, to produce real evidence, and to ask you
75
89
  before writing any proof on your behalf.
76
90
 
77
91
  ## What counts as a peer review
@@ -118,7 +132,8 @@ apart. Record it in a `vqm-proof.json` file, in the repository or any parent fol
118
132
  }
119
133
  ```
120
134
 
121
- A proof only turns **Not visible** into **Met (attested)**. It never overrides **Not
135
+ A proof only turns **Not visible** (or **In place**, for history the tool does not
136
+ claim) into **Met (attested)**. It never overrides **Not
122
137
  met**, because what the tool saw outranks what anyone says. Proof is signed by a
123
138
  named person and expires after a year.
124
139
 
@@ -130,12 +145,12 @@ that caused it. The report appears on the run's summary page.
130
145
  ```yaml
131
146
  - uses: actions/checkout@v4
132
147
  with: { fetch-depth: 0 } # the checks sample history
133
- - uses: vibeqm/vibeqm-check@v0.4.3
148
+ - uses: vibeqm/vibeqm-check@v0.4.7
134
149
  with: { min-level: 2 } # optional: fail the run below this level
135
150
  ```
136
151
 
137
- To let the action read the repository's CI runs and pull requests, give the job
138
- read access (`permissions: { contents: read, actions: read, pull-requests: read }`).
152
+ To let the action read the repository's CI runs, pull requests and branch rules,
153
+ give the job read access (`permissions: { contents: read, actions: read, pull-requests: read }`).
139
154
  Pass `offline: true` to read the repository only.
140
155
 
141
156
  ## What it is, and what it is not
@@ -110,7 +110,7 @@ export function requirementsFirst(root) {
110
110
  // and not filled in yet: it doesn't carry the gate alone.
111
111
  const filledDocs = found.filter((f) => !f.startsWith(".github/ISSUE_TEMPLATE/"));
112
112
  if (found.length && (filledDocs.length || !unfilled.length))
113
- return r(2, gate, "met", `requirements or issue templates in the repository: ${found.slice(0, 3).join(", ")}${found.length > 3 ? "…" : ""}${note ? `; ${note}` : ""}`);
113
+ return r(2, gate, "met", `requirements or issue templates in the repository: ${found.slice(0, 3).join(", ")}${found.length > 3 ? "…" : ""}${note ? `; ${note}` : ""}. Whether each change traces to one is a judgment question of the full assessment`);
114
114
  if (unfilled.length)
115
115
  return r(2, gate, "not-met", `${note}: fill it with this project's requirements, or delete it`);
116
116
  return r(2, gate, "not-visible", "no requirements file or issue templates in the repository; if requirements live in an issue tracker, attach proof that every change traces to one and that unclear requests get clarifying questions with options");
@@ -208,15 +208,34 @@ export function peerReview(root) {
208
208
  const trailers = commits.filter((c) => c.trailer).length;
209
209
  return r(2, gate, "not-visible", `${trailers ? `${trailers} of the last ${commits.length} commits carry a \`Reviewed-by:\` trailer, but none has a matching review record (a review file in the commit, or one naming it)` : `no reviewed changes found in the last ${commits.length} commits (a \`Reviewed-by:\` trailer plus a review record, or a reviewed pull request)`}; ${need}`);
210
210
  }
211
- const first = commits[firstAt];
212
- const since = commits.slice(0, firstAt + 1).filter((c) => !c.recordsOnly && due(c));
213
- const missing = since.filter((c) => !c.reviewed);
214
- const waiting = commits.slice(0, firstAt + 1).filter((c) => !c.recordsOnly && !due(c) && !c.reviewed).length;
215
- const head = `since review began (${first.short}, ${first.date}), ${since.length - missing.length} of ${since.length} pushed commits were covered by a review${waiting ? ` (${waiting} not pushed yet, due at the next push)` : ""}`;
216
- if (missing.length)
217
- return r(2, gate, "not-met", `${head}; not reviewed: ${missing.slice(0, 5).map((c) => c.short + (c.trailer ? " (trailer, no review record)" : "")).join(", ")}${missing.length > 5 ? "…" : ""}`);
218
- if (since.length < MIN_SINCE)
219
- return r(2, gate, "not-visible", `${head}; ${MIN_SINCE} changes since adoption are needed before this counts (earlier history needs proof)`);
211
+ // One unreviewed pushed change after adoption restarts the count at the next
212
+ // reviewed change (DEC-148): the gate names the change that broke the run, and the
213
+ // person recovers by reviewing from then on, instead of waiting for the sample to forget.
214
+ const window = commits.slice(0, firstAt + 1);
215
+ const brokeAt = window.findIndex((c) => !c.recordsOnly && due(c) && !c.reviewed);
216
+ let startAt = firstAt;
217
+ let restart = "";
218
+ if (brokeAt >= 0) {
219
+ const broke = window[brokeAt];
220
+ const resumed = window.slice(0, brokeAt).map((c) => c.reviewed && !c.recordsOnly).lastIndexOf(true);
221
+ const note = `${broke.short} (${broke.date}${broke.trailer ? ", trailer but no review record" : ""})`;
222
+ if (resumed < 0)
223
+ return r(2, gate, "not-met", `review began at ${commits[firstAt].short} (${commits[firstAt].date}), but the latest pushed change was not reviewed: ${note}; the count restarts at the next reviewed change`);
224
+ startAt = resumed;
225
+ restart = ` (restarted at ${window[resumed].short} after the unreviewed change ${note})`;
226
+ }
227
+ const first = commits[startAt];
228
+ const since = commits.slice(0, startAt + 1).filter((c) => !c.recordsOnly && due(c));
229
+ const waiting = commits.slice(0, startAt + 1).filter((c) => !c.recordsOnly && !due(c) && !c.reviewed).length;
230
+ const head = `since review began (${first.short}, ${first.date})${restart}, ${since.length} of ${since.length} pushed changes were covered by a review${waiting ? ` (${waiting} not pushed yet, due at the next push)` : ""}`;
231
+ if (since.length < MIN_SINCE) {
232
+ // Review is set up and every pushed change since has one: the gate is in place
233
+ // and counts once 20 reviewed changes have followed adoption (ASSESSOR §2, DEC-087).
234
+ return {
235
+ ...r(2, gate, "in-place", `${head}; counts after ${MIN_SINCE} reviewed changes since adoption, ${since.length} so far; one unreviewed push restarts the count (earlier history needs proof)`),
236
+ progress: { done: since.length, needed: MIN_SINCE, unit: "reviewed changes" },
237
+ };
238
+ }
220
239
  return r(2, gate, "met", `${head} (a push review, a reviewed pull request, or a trailer with a review record); earlier history is not claimed`);
221
240
  }
222
241
  export function verificationTools(root) {
@@ -226,7 +245,11 @@ export function verificationTools(root) {
226
245
  const pkg = files.includes("package.json") && /"(lint|typecheck)"\s*:/.test(read(root, "package.json"));
227
246
  const cargo = files.filter((f) => /(^|\/)Cargo\.toml$/.test(f)).some((f) => /^\[(workspace\.)?lints/m.test(read(root, f)));
228
247
  const tsStrict = files.filter((f) => /(^|\/)tsconfig[^/]*\.json$/.test(f)).some((f) => /"strict"\s*:\s*true/.test(read(root, f)));
229
- const run = code(ciText(root, files) + "\n" + hookText(root)).match(ANALYZE_COMMANDS)?.[0];
248
+ const wired = code(ciText(root, files) + "\n" + hookText(root));
249
+ const run = wired.match(ANALYZE_COMMANDS)?.[0];
250
+ // The gate is that the checks run on every change: a hook or CI job must run the
251
+ // analyzer, or at least the project's test or lint command, beside the configuration.
252
+ const runs = wired.match(CHECK_COMMANDS)?.[0];
230
253
  const gate = "Verification on every change";
231
254
  const ev = [
232
255
  ...lint.slice(0, 3),
@@ -236,8 +259,10 @@ export function verificationTools(root) {
236
259
  ...(tsStrict ? ["tsconfig strict mode"] : []),
237
260
  ...(run ? [`\`${run.trim()}\` runs in a hook or CI`] : []),
238
261
  ];
262
+ if (ev.length && (run || runs))
263
+ return r(2, gate, "met", `linter or static-analysis configuration: ${ev.join(", ")}; a hook or CI job runs \`${(run ?? runs ?? "").trim()}\` (that a failure blocks the change is the "Checks before merge" gate)`);
239
264
  if (ev.length)
240
- return r(2, gate, "met", `linter or static-analysis configuration: ${ev.join(", ")} (that it runs and blocks is the "Checks before merge" gate)`);
265
+ return r(2, gate, "not-met", `linter or static-analysis configuration: ${ev.join(", ")}, but no enabled hook or CI job runs it or the tests: add the command to .githooks/pre-commit (enabled with \`git config core.hooksPath .githooks\`) or to the CI workflow`);
241
266
  return r(2, gate, "not-met", "no linter or static-analysis configuration found, and no analyzer command in a hook or CI. If the project uses an analyzer this tool does not recognise, run it from the pre-commit hook or CI (e.g. `dart analyze`, `cargo clippy`, `tsc --noEmit`) and it will be found");
242
267
  }
243
268
  export function securityBeforePush(root) {
@@ -258,7 +283,13 @@ export function securityBeforePush(root) {
258
283
  const thinShare = code_.length ? code_.filter((f) => thin.some((e) => f.endsWith(e))).length / code_.length : 0;
259
284
  const reviewTools = ["security-review", "codeql", "semgrep", "snyk", "bandit", "ruff security rules (bandit)"].filter((x) => tools.includes(x));
260
285
  const note = reviewTools.length === 1 && reviewTools[0] === "semgrep" && thinShare > 0.3 ? " (note: Semgrep's rules barely cover this repository's main language; an AI security review of each push covers it better)" : "";
261
- const ev = `found: ${[...tools, ...(dependabot ? ["dependabot"] : [])].join(", ")}${note}`;
286
+ const secretTools = tools.filter((x) => ["gitleaks", "trufflehog", "detect-secrets", "git-secrets"].includes(x));
287
+ const depTools = [...tools.filter((x) => ["osv-scanner", "npm audit", "pip-audit", "trivy", "dependency-review", "snyk"].includes(x)), ...(dependabot ? ["dependabot"] : [])];
288
+ const ev = [
289
+ `secret scanning: ${secretTools.join(", ") || "none"}`,
290
+ `security review of each change (an AI review or static security analysis): ${reviewTools.join(", ") || "none"}${note}`,
291
+ `dependency scan: ${depTools.join(", ") || "none"}${depTools.length ? " (whether it blocks on critical findings is a CI or host setting, not checked)" : ""}`,
292
+ ].join("; ");
262
293
  if (hasSecrets && hasReview)
263
294
  return r(2, gate, "met", ev);
264
295
  return r(2, gate, "not-met", `${ev}; missing ${[!hasReview ? "an AI or static security review of each change" : "", !hasSecrets ? "secret scanning" : ""].filter(Boolean).join(" and ")}`);
@@ -357,10 +388,12 @@ export function committedSettings(root) {
357
388
  return null;
358
389
  }
359
390
  };
391
+ // A committed file is named by its path in the repository, never by this machine's
392
+ // absolute path: the evidence goes into reports people share.
360
393
  return [
361
- ...project.map((f) => (inHead.has(f) ? { file: join(root, f), committed: true, text: git(root, ["show", `HEAD:${f}`]) } : { file: join(root, f), committed: false, text: disk(join(root, f)) })),
394
+ ...project.map((f) => (inHead.has(f) ? { file: f, committed: true, text: git(root, ["show", `HEAD:${f}`]) } : { file: f, committed: false, text: disk(join(root, f)) })),
362
395
  { file: join(homedir(), ".claude", "settings.json"), committed: false, text: disk(join(homedir(), ".claude", "settings.json")) },
363
- ].filter((s) => s.committed || existsSync(s.file));
396
+ ].filter((s) => s.committed || existsSync(s.file.startsWith("/") ? s.file : join(root, s.file)));
364
397
  }
365
398
  /** Where the agent is told, or made, to ask before publishing live. */
366
399
  function confirmationRule(root) {
@@ -383,7 +416,7 @@ function confirmationRule(root) {
383
416
  continue;
384
417
  const list = `${hits.slice(0, 3).join(", ")}${hits.length > 3 ? "…" : ""}`;
385
418
  if (committed)
386
- found.push(`publish commands that stop for the person or are refused in ${file.slice(root.length + 1)}: ${list}`);
419
+ found.push(`publish commands that stop for the person or are refused in ${file}: ${list}`);
387
420
  else
388
421
  machineOnly.push(`${file} (this machine's settings, not committed): ${list}`);
389
422
  }
@@ -467,8 +500,13 @@ export function configurationBasics(root) {
467
500
  const tags = (git(root, ["tag", "--list"]) ?? "").split("\n").filter(Boolean);
468
501
  const remote = tags.length ? hostTags(root) : null;
469
502
  const versions = tags.filter((t) => /^v?\d+(\.\d+)+/.test(t));
470
- if (!tags.length)
471
- problems.push("no release tags");
503
+ // Nothing released yet, said in the rules file or the README, needs no tag (DEC-147);
504
+ // the first release is tagged. A template's blank is a choice, not a statement.
505
+ const notLive = [...RULES_FILES, "README.md"].map((f) => read(root, f).split("\n").find((l) => NOT_LIVE.test(l) && !placeholders(l).length)).find(Boolean);
506
+ if (!tags.length && notLive)
507
+ ok.push(`no release tags yet, and the repository says nothing is released: "${notLive.trim().slice(0, 60)}" (tag the first release)`);
508
+ else if (!tags.length)
509
+ problems.push("no release tags (if nothing is released yet, say so in the rules file or the README: \"nothing is live yet\")");
472
510
  else if (remote && !tags.some((t) => remote.includes(t)))
473
511
  problems.push(`${tags.length} release tag(s) here, none pushed to the host`);
474
512
  else
@@ -3,7 +3,7 @@
3
3
  import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
4
4
  import { join, relative } from "node:path";
5
5
  import { commitSizes, git, median } from "../git.js";
6
- import { defaultBranchRuns, mergedPullRequests } from "../host.js";
6
+ import { branchRules, defaultBranchRuns, mergedPullRequests } from "../host.js";
7
7
  import { blanksNote, CHECK_COMMANDS, code, committedSettings, delegated, placeholders, RULES_FILES } from "./basics.js";
8
8
  const SMALL_BATCH_LIMIT = 400; // ASSESSOR §2: median changed lines per merged change
9
9
  const SAMPLE = 100;
@@ -31,6 +31,50 @@ export function agentRulesFile(root) {
31
31
  const lines = filled.map((f) => `${f} (${text(f).split("\n").length} lines)`);
32
32
  return { level: 2, gate, status: "met", evidence: [...lines, ...blanks].join("; ") };
33
33
  }
34
+ /** The accepted equivalent of pull requests for a one-person repository (VQM_SPEC §6,
35
+ * DEC-147): a committed blocking hook, the bypass denied in committed agent settings,
36
+ * and a tailoring row that records it. Each part is named, so the evidence says what
37
+ * is missing when it is not met. */
38
+ function soloEquivalent(root) {
39
+ const authors = new Set((git(root, ["log", `-${SAMPLE}`, "--format=%ae"]) ?? "").split("\n").filter(Boolean));
40
+ const solo = authors.size === 1;
41
+ const have = [];
42
+ const missing = [];
43
+ const hook = blockingHooks(root).find((h) => h.committed);
44
+ if (hook)
45
+ have.push(`the committed blocking ${hook.name} hook (${hook.rel})`);
46
+ else
47
+ missing.push("a committed blocking pre-commit or pre-push hook (see Checks before merge)");
48
+ const denied = committedSettings(root).find(({ committed, text }) => {
49
+ if (!committed)
50
+ return false;
51
+ try {
52
+ return (JSON.parse(text ?? "")?.permissions?.deny ?? []).some((d) => typeof d === "string" && /--no-verify|-n /.test(d));
53
+ }
54
+ catch {
55
+ return false;
56
+ }
57
+ });
58
+ if (denied)
59
+ have.push(`\`--no-verify\` denied in ${denied.file}`);
60
+ else
61
+ missing.push("a deny rule on `git commit --no-verify` in .claude/settings.json, committed");
62
+ const tailoring = (git(root, ["ls-files", "--", "VibeQM/tailoring/", "tailoring/"]) ?? "")
63
+ .split("\n")
64
+ .filter((f) => /\.md$/i.test(f))
65
+ .map((f) => {
66
+ const row = readFileSync(join(root, f), "utf8")
67
+ .split("\n")
68
+ .find((l) => /^\|\s*TLR-\d+/.test(l) && /pull request|merge path|branch protection/i.test(l) && !placeholders(l).length);
69
+ return row ? `${f} (${row.match(/TLR-\d+/)?.[0]})` : null;
70
+ })
71
+ .find(Boolean);
72
+ if (tailoring)
73
+ have.push(`recorded as tailoring in ${tailoring}`);
74
+ else
75
+ missing.push("a tailoring row (VibeQM/tailoring/TAILORING.md) saying the hook stands in for pull requests, approved by the owner");
76
+ return { solo, have, missing };
77
+ }
34
78
  export function versionControl(root) {
35
79
  const gate = "Version control + merge path";
36
80
  if (git(root, ["rev-parse", "--git-dir"]) === null) {
@@ -44,11 +88,27 @@ export function versionControl(root) {
44
88
  if (prs?.length) {
45
89
  return { level: 2, gate, status: "met", evidence: `${prs.length} pull requests merged on the host (e.g. #${prs[0].number}, ${prs[0].mergedAt.slice(0, 10)})` };
46
90
  }
91
+ const rules = branchRules(root);
92
+ if (rules?.pullRequest) {
93
+ return { level: 2, gate, status: "met", evidence: `the host requires a pull request before merging into ${rules.branch} (read from the host with your login)` };
94
+ }
95
+ const { solo, have, missing } = soloEquivalent(root);
96
+ if (solo && !missing.length) {
97
+ return { level: 2, gate, status: "met", evidence: `one author in the sample; changes reach the main branch behind ${have.join(", ")}: the accepted equivalent of pull requests for a one-person repository` };
98
+ }
99
+ if (solo) {
100
+ return {
101
+ level: 2,
102
+ gate,
103
+ status: "not-visible",
104
+ evidence: `git repository with one author and no merge commits. For one person, the accepted equivalent of pull requests needs ${missing.join("; ")}${have.length ? ` (already there: ${have.join(", ")})` : ""}. Or branch protection on the host, which this tool reads when the GitHub CLI is logged in`,
105
+ };
106
+ }
47
107
  return {
48
108
  level: 2,
49
109
  gate,
50
110
  status: "not-visible",
51
- evidence: "git repository, but no merge commits in the sample. Branch protection is set on the host (e.g. GitHub) and can't be read locally; a tailoring record may let a blocking pre-commit gate stand in for pull requests",
111
+ evidence: "git repository, but no merge commits in the sample. Branch protection is set on the host (e.g. GitHub); this tool reads it when the GitHub CLI is logged in, otherwise attach proof",
52
112
  };
53
113
  }
54
114
  function hooksDir(root) {
@@ -58,24 +118,12 @@ function hooksDir(root) {
58
118
  const gitDir = git(root, ["rev-parse", "--absolute-git-dir"])?.trim();
59
119
  return gitDir ? join(gitDir, "hooks") : null;
60
120
  }
61
- export function checksBeforeMerge(root) {
62
- const gate = "Checks before merge";
63
- const evidence = [];
64
- const workflows = join(root, ".github", "workflows");
65
- if (existsSync(workflows)) {
66
- const files = readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f));
67
- if (files.length)
68
- evidence.push(`CI workflows: ${files.join(", ")}`);
69
- }
70
- for (const f of [".gitlab-ci.yml", ".circleci/config.yml", "azure-pipelines.yml"]) {
71
- if (existsSync(join(root, f)))
72
- evidence.push(`CI config: ${f}`);
73
- }
74
- // A hook counts when it runs a test, lint or analyze command (itself or through
75
- // the Makefile or a repository script it calls); `exit 0` is not a gate.
76
- // core.hooksPath is per-clone config, so say where the hook lives.
121
+ /** The executable pre-commit and pre-push hooks that run a test, lint or analyze
122
+ * command (themselves or through the Makefile or a repository script they call);
123
+ * `exit 0` is not a gate. `idle` names hooks that run nothing recognisable. */
124
+ function blockingHooks(root, idle = []) {
77
125
  const hooks = hooksDir(root);
78
- const idle = [];
126
+ const found = [];
79
127
  for (const name of ["pre-commit", "pre-push"]) {
80
128
  const p = hooks ? join(hooks, name) : null;
81
129
  if (!p || !existsSync(p) || !(statSync(p).mode & 0o111))
@@ -87,26 +135,58 @@ export function checksBeforeMerge(root) {
87
135
  continue;
88
136
  }
89
137
  const rel = relative(realpathSync(root), realpathSync(p));
138
+ const committed = !rel.startsWith("..") && !!(git(root, ["ls-files", "--", rel]) ?? "").trim();
90
139
  const where = rel.startsWith("..")
91
140
  ? "a shared hook outside the repository, enabled on this machine"
92
- : (git(root, ["ls-files", rel]) ?? "").trim()
141
+ : committed
93
142
  ? `committed in the repository (${rel}); each clone enables it with \`git config core.hooksPath\``
94
143
  : "enabled on this machine only, not committed";
95
- evidence.push(`blocking git hook ${name} runs \`${runs.trim()}\`: ${where}`);
144
+ found.push({ name, runs: runs.trim(), rel, committed, where });
96
145
  }
146
+ return found;
147
+ }
148
+ export function checksBeforeMerge(root) {
149
+ const gate = "Checks before merge";
150
+ const evidence = [];
151
+ const workflows = join(root, ".github", "workflows");
152
+ if (existsSync(workflows)) {
153
+ const files = readdirSync(workflows).filter((f) => /\.ya?ml$/.test(f));
154
+ if (files.length)
155
+ evidence.push(`CI workflows: ${files.join(", ")}`);
156
+ }
157
+ for (const f of [".gitlab-ci.yml", ".circleci/config.yml", "azure-pipelines.yml"]) {
158
+ if (existsSync(join(root, f)))
159
+ evidence.push(`CI config: ${f}`);
160
+ }
161
+ // core.hooksPath is per-clone config, so say where the hook lives.
162
+ const idle = [];
163
+ for (const h of blockingHooks(root, idle))
164
+ evidence.push(`blocking git hook ${h.name} runs \`${h.runs}\`: ${h.where}`);
165
+ // A committed hook that this clone has not enabled (core.hooksPath unset) blocks
166
+ // nothing yet; say so, since enabling it is one command.
167
+ const dormant = ["pre-commit", "pre-push"]
168
+ .map((n) => `.githooks/${n}`)
169
+ .filter((f) => (git(root, ["ls-files", "--", f]) ?? "").trim() && existsSync(join(root, f)) && code(readFileSync(join(root, f), "utf8")).match(CHECK_COMMANDS));
170
+ const enabled = git(root, ["config", "core.hooksPath"])?.trim();
171
+ const notEnabled = dormant.length && !enabled ? `; ${dormant.join(" and ")} is committed but not enabled on this clone: run \`git config core.hooksPath .githooks\`` : "";
97
172
  if (idle.length && !evidence.length) {
98
- return { level: 2, gate, status: "not-met", evidence: `${idle.join(" and ")} hook found, but it runs no test, lint or analyze command this tool recognises` };
173
+ return { level: 2, gate, status: "not-met", evidence: `${idle.join(" and ")} hook found, but it runs no test, lint or analyze command this tool recognises${notEnabled}` };
99
174
  }
100
175
  if (!evidence.length) {
101
- return { level: 2, gate, status: "not-met", evidence: "no CI configuration and no executable pre-commit/pre-push hook" };
176
+ return { level: 2, gate, status: "not-met", evidence: `no CI configuration and no executable pre-commit/pre-push hook${notEnabled}` };
102
177
  }
103
- // CI that runs is not the same as CI that blocks: required status checks live on the host.
178
+ // CI that runs is not the same as CI that blocks: required status checks live on the
179
+ // host, read here when the GitHub CLI is logged in.
104
180
  const onlyCi = !evidence.some((e) => e.startsWith("blocking git hook"));
181
+ const required = onlyCi ? branchRules(root)?.requiredChecks ?? [] : [];
182
+ if (onlyCi && required.length) {
183
+ return { level: 2, gate, status: "met", evidence: `${evidence.join("; ")}; the host requires ${required.slice(0, 3).join(", ")}${required.length > 3 ? "…" : ""} to pass before merging (read from the host with your login)` };
184
+ }
105
185
  return {
106
186
  level: 2,
107
187
  gate,
108
188
  status: onlyCi ? "not-visible" : "met",
109
- evidence: evidence.join("; ") + (onlyCi ? ". Whether failing CI blocks the merge is a host setting; attach proof" : ""),
189
+ evidence: evidence.join("; ") + (onlyCi ? `. Whether failing CI blocks the merge is a host setting: this tool reads it when the GitHub CLI is logged in; otherwise a committed blocking hook makes it visible, or attach proof${notEnabled}` : ""),
110
190
  };
111
191
  }
112
192
  export function smallBatches(root) {
@@ -194,4 +194,6 @@ export const level3 = [
194
194
  notVisible("Agent plug-ins and tools", "outside plug-ins, tool servers and skills must be pinned and added as high-risk changes; attach proof"),
195
195
  notVisible("Parallel agents and rollback", "agents on separate branches through the same checks, and a tried rollback; attach proof"),
196
196
  notVisible("Generated-code licensing", "a license check on new code; attach proof"),
197
+ notVisible("Reviewer proven", "the AI peer reviewer's model and version need a record of catching a planted-fault set (at least five known-bad changes, including a weakened test and a prompt-injection case), kept where the agent can't edit it; attach proof"),
198
+ notVisible("Service-bound items (applicability)", "a product with no live production service states an equivalent or a not-applicable reason for each service-bound item, recorded as tailoring; attach proof"),
197
199
  ];
package/dist/src/cli.js CHANGED
@@ -3,7 +3,7 @@
3
3
  // run the VibeQM fact checks on a repository. vibeqm-check init [path] [--yes]: create the
4
4
  // Level 2 template files.
5
5
  import { existsSync, statSync, writeFileSync } from "node:fs";
6
- import { resolve } from "node:path";
6
+ import { relative, resolve } from "node:path";
7
7
  import { level2 } from "./checks/level2.js";
8
8
  import { level3 } from "./checks/level3.js";
9
9
  import { basics2, basics3 } from "./checks/basics.js";
@@ -22,11 +22,14 @@ if (args[0] === "init") {
22
22
  console.log(`vibeqm-check init [path] [--yes]
23
23
 
24
24
  Create the VibeQM Level 2 template files in a repository: a rules file for AI agents,
25
- agent permissions, a CI workflow with security checks, issue and pull request
26
- templates, and short requirements, decisions and plan files under VibeQM/.
25
+ agent permissions, a blocking pre-commit hook, a CI workflow with security checks,
26
+ issue and pull request templates, and short requirements, decisions and plan files
27
+ under VibeQM/. Blanks the repository answers (the test and build commands, the
28
+ description) are filled; the rest are left as <...> for you or your agent.
27
29
 
28
30
  It lists every file first, skips files that already exist, and writes only after you
29
- say yes. It never overwrites a file, never commits, and installs no hooks.
31
+ say yes. It never overwrites a file, never commits, and enables no hook (the hook it
32
+ writes is enabled with one command, git config core.hooksPath .githooks).
30
33
 
31
34
  path the repository (default: the current directory)
32
35
  --yes create the files without asking (needed when not run in a terminal)
@@ -117,7 +120,9 @@ if (oi >= 0 && (!outArg || outArg.startsWith("-"))) {
117
120
  const root = resolve(args.find((a, i) => !a.startsWith("--") && (pi < 0 || i !== pi + 1) && (oi < 0 || i !== oi + 1)) ?? ".");
118
121
  let results = [...level2, ...basics2, ...level3, ...basics3].map((check) => check(root));
119
122
  const proofFiles = proofArg ? [resolve(proofArg)] : findProofFiles(root);
120
- const proofFile = proofFiles.length ? proofFiles.join(", ") : null;
123
+ // Named by their path in the repository when inside it: the report is for sharing, and
124
+ // an absolute path carries the machine's layout and the account name.
125
+ const proofFile = proofFiles.length ? proofFiles.map((f) => (f.startsWith(`${root}/`) ? relative(root, f) : f)).join(", ") : null;
121
126
  if (proofFiles.length) {
122
127
  try {
123
128
  const merged = mergeProofs(proofFiles);
@@ -187,10 +192,10 @@ else if (process.stdin.isTTY && process.stdout.isTTY && !args.includes("--all"))
187
192
  const prompt = aiPrompt(results);
188
193
  // With nothing open at the next level there is no to-do list to wait for.
189
194
  if (prompt)
190
- await ask("Press Enter to show what to do next (q quits). ");
195
+ await ask("Press Enter for the list of what to do (q quits). ");
191
196
  console.log(`\n${terminalDetails(results, proofFile, style)}\n`);
192
197
  if (prompt) {
193
- await ask("Press Enter to show a prompt your AI can use to bring this repository to the next level (q quits). ");
198
+ await ask("Press Enter for the prompt to paste into your AI coding agent (q quits). ");
194
199
  console.log(`\n${prompt}\n`);
195
200
  }
196
201
  rl.close();