@antelopejs/tooling-configs 0.2.10 → 0.2.12

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/dist/bin/sync.mjs CHANGED
@@ -3,10 +3,11 @@ import { a as formatCeilings, o as isRetired, s as readCeilings, t as CEILINGS_F
3
3
  import { t as runCli } from "../cli-4Tv71vYk.mjs";
4
4
  import { o as repositoryRoot } from "../files-2FikHZ9F.mjs";
5
5
  import { a as repositoryTools, i as parseManifest, n as managedPackage, o as toolingVersions, r as packageManager, t as execCommand } from "../package-Dtjt_lSa.mjs";
6
- import { t as measureBaseline } from "../ratchet-B2qYUs51.mjs";
7
- import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Bq30tJDS.mjs";
6
+ import { t as measureBaseline } from "../ratchet-DRdIYwmv.mjs";
7
+ import { n as SUPPRESSIONS_FILE, r as adoptedBudget } from "../suppression-budget-Yyf5_J5l.mjs";
8
8
  import { a as ciWorkflow, c as ciNodeCallers, i as MUTATION_PATH, l as hasChecksWorkflow, o as mutationCaller, r as CI_PATH, s as MISSING_CHECKS_WORKFLOW } from "../ci-workflow-BDy6hQJ6.mjs";
9
- import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
9
+ import { a as skillFolder, i as isVerifyKind, n as claudeLink, r as claudeLinkTarget, t as VERIFY_KINDS } from "../kinds-Bzyyi9yk.mjs";
10
+ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
10
11
  import { dirname, join, resolve } from "node:path";
11
12
  import { execFileSync } from "node:child_process";
12
13
  import { parseArgs } from "node:util";
@@ -50,6 +51,7 @@ const SHARED_RULES = [
50
51
  ["Comments are TSDoc, directives, or `SAFETY:` only", "`antelopejs/no-comments`"],
51
52
  ["Every test asserts", "`antelopejs/require-assertion`"],
52
53
  ["Tests read no files outside fixtures, helpers, locales", "`antelopejs/no-fs-read-in-tests`"],
54
+ ["Tests import the code under test from local source, not their own package name", "`antelopejs/no-self-import-in-tests`"],
53
55
  ["No assertion that restates a constant", "`antelopejs/no-constant-value-assertion`"],
54
56
  ["No test whose only check is \"is a function\"", "`antelopejs/no-typeof-function-only-test`"],
55
57
  ["Params ≤ 5, function ≤ 120 lines, file ≤ 500 lines, depth ≤ 4, complexity ≤ 20", "`eslint/max-*`, `eslint/complexity`"],
@@ -339,6 +341,349 @@ function checkEntryOnlyConfiguration(root) {
339
341
  advisories
340
342
  };
341
343
  }
344
+ /** The kind-specific text of each shared skill. */
345
+ const KIND_TEXT = {
346
+ interface: {
347
+ description: "Drive this AntelopeJS interface the way a module author does: pack it, load it in `ajs project dev` next to a stub provider wired through ImplementInterface and a consumer, call every declared function through core, and check the minor-bump rule against the published version. Use to prove a change to the interface works before merge, to verify a PR, or to check that a seeded break is caught.",
348
+ title: "Verify interface",
349
+ user: "The user of an interface is a module author: one module implements it, others import it and call its functions through core.",
350
+ launch: "`new` runs the setup (`pnpm run build` by default), then packs the interface with `pnpm pack` and extracts it, so journeys load what npm would publish, `files` and `exports` included.",
351
+ builtins: `- \`every-function\`: a fixture project loads the packed interface with a stub provider and a consumer module. The consumer walks the loaded interface, and every function the \`.d.ts\` files declare is called through core:
352
+ - an async proxy answers the stub's echo, and the stub's call log shows the same arguments (the second view);
353
+ - a registering proxy registers and unregisters, and the stub logs both;
354
+ - an event proxy delivers the emitted arguments to a registered handler;
355
+ - a plain function runs the \`interface.calls\` hook of \`verify.config.ts\` and must return its \`expect\`; one only providers call is listed in \`interface.providerSide\` with why.
356
+ A declared function with none of these fails the journey.
357
+ - \`minor-bump\`: reads the declared functions of the packed head and of the published version (\`npm pack <name>@<latest>\`). An added, changed or removed function needs a release of at least the next minor. The release is the head version when it is already bumped, otherwise what changelogen makes of the change title (\`new --title\`) or the commit subjects since the base.`,
358
+ layer: `- \`interface.provide(api)\` runs in the stub provider after the generic stubs attach, for example to hand a stub client to \`internal.SetClient\`.
359
+ - \`interface.calls["<entry>:<path>"]\` calls a plain exported function from the consumer and states the value it must return.
360
+ - \`interface.providerSide["<entry>:<path>"]\` names a function only providers call, with the reason.`,
361
+ smoke: "`every-function`",
362
+ gotchas: ["A function the consumer awaits forever, such as a getter no provider resolved, fails after 15 seconds with a `Timeout` value.", "`minor-bump` needs the npm registry. Without it the journey is not verified, never passed."]
363
+ },
364
+ module: {
365
+ description: "Drive this AntelopeJS implementation module the way an app developer does: install it as `local` in a fixture project, run its backing services in Docker on free ports, call its interfaces from a consumer module and read stored state back with the service's native client. Use to prove a change to the module works before merge, to verify a PR, or to check that a seeded break is caught.",
366
+ title: "Verify module",
367
+ user: "The user of a module is an app developer: they add it to `antelope.config.ts`, configure it, and other modules call the interfaces it implements.",
368
+ launch: "`new` runs the setup (`pnpm run build` by default), then starts every `services` entry of `verify.config.ts` in its own Docker container on a free loopback port, named `<prefix>-<repo>-<service>-<run>` (`VERIFY_CONTAINER_PREFIX`, default `verify`), and waits for each readiness command. A provider with sandbox keys in `saas.env` records the missing ones.",
369
+ builtins: "- `module-dev`: a fixture project installs the module as `local` with `moduleConfig(services)` as its config, plus a consumer module. `ajs project dev` must answer, the consumer must load every implemented interface, Ctrl+C must exit 130 and the port must refuse afterwards.",
370
+ layer: `- \`services\`: image, port, readiness command and a \`reset\` command run before every journey, so each starts from a clean state.
371
+ - \`moduleConfig(services)\`: the module's configuration, pointing at the run's containers.
372
+ - \`saas: { env, sandbox }\`: a SaaS module runs against the provider's sandbox with keys from these environment variables. Without every key, each journey is not verified and so is the verdict, never PASS.
373
+ - \`journeys\`: the module's own journeys. Each writes through the module with \`context.call(...)\` and reads the result back with \`context.native(...)\` (\`redis-cli\`, \`mongosh\`, \`psql\`, the Mailpit API) inside the service container.`,
374
+ smoke: "`module-dev` and one write read back through the native client",
375
+ gotchas: ["Every container is the run's own. Never point a journey at a shared instance such as a developer's local database.", "A sandbox key missing from the environment is a NOT VERIFIED verdict, which sets status `verify` to `error`."]
376
+ },
377
+ template: {
378
+ description: "Drive this AntelopeJS template the way a new user does: scaffold a project with `ajs project init` from an offline interfaces manifest, install it, run its own `pnpm run checks`, run `ajs project dev --watch` and hit its welcome page, endpoint or ready line. Use to prove a change to the template works before merge, to verify a PR, to run the release canary, or to check that a seeded break is caught.",
379
+ title: "Verify template",
380
+ user: "The user of a template is someone running `ajs project init --template`: they get a copy of the whole repository and expect it to install, pass its checks and run.",
381
+ launch: "`new` copies the working tree, uncommitted changes included, into a local git repository, and lists it in an offline interfaces manifest (`templates`, or `projectTemplates` when `template.project` is set) under `template.name`. Journeys point `ajs config set git` at it, so no step reaches GitHub.",
382
+ builtins: `- \`scaffold-dev\`: \`ajs project init <app> --template <name> --pm pnpm --git-init\`, \`pnpm install --frozen-lockfile\`, then \`ajs project dev --watch\` with \`PORT\` set until \`template.probe\` answers: a path and status on that port, or a \`log\` line followed by \`settleMs\` of still running. Ctrl+C must exit 130.
383
+ - \`scaffold-checks\`: the same scaffold and install, then the project's own \`pnpm run checks\`.`,
384
+ layer: `- \`template.name\`: the listing name users pass to \`--template\`.
385
+ - \`template.project\`: list it under \`projectTemplates\`.
386
+ - \`template.probe\`: \`path\`, \`status\` and \`body\` for an HTTP welcome page or endpoint, or \`log\` and \`settleMs\` for a template that serves nothing.`,
387
+ smoke: "`scaffold-dev` and `scaffold-checks`",
388
+ gotchas: ["`ajs` copies the whole repository, `.agents/` and `.claude/` included, so the scaffolded project carries this skill too.", "Every file a user gets is user-facing here, tests included; only `.agents/`, `.claude/` and `.github/` are not."]
389
+ }
390
+ };
391
+ //#endregion
392
+ //#region src/verify/skills.ts
393
+ const BIN = "pnpm exec antelopejs-verify";
394
+ function bullets(lines) {
395
+ return lines.map((line) => `- ${line}`).join("\n");
396
+ }
397
+ /** The synced SKILL.md of a kind, the part of the skill `antelopejs-sync` owns. */
398
+ function skillText(kind) {
399
+ const text = KIND_TEXT[kind];
400
+ const folder = skillFolder(kind);
401
+ return `---
402
+ name: verify-${kind}
403
+ description: ${JSON.stringify(text.description)}
404
+ ---
405
+
406
+ # ${text.title}
407
+
408
+ ${text.user} Every deterministic step is an \`antelopejs-verify\` command: you choose which journeys to run and judge what they show. Never replace a command with a shell recipe. When a journey you need does not exist, add it to \`verify.config.ts\`, name it in its feature file, then run it.
409
+
410
+ \`antelopejs-sync\` writes this file and \`package.json\` here, and keeps them in sync. Everything else in \`${folder}/\` is the repository's own layer, which sync never touches.
411
+
412
+ ## Launch
413
+
414
+ \`\`\`bash
415
+ ${BIN} new --base origin/main --title "<PR title>"
416
+ \`\`\`
417
+
418
+ \`new\` prints the run folder; pass it as \`<run>\` below. ${text.launch} Every journey gets its own \`HOME\` and scratch folder, \`CI=1\`, \`AJS_NO_UPDATE_CHECK=1\`, \`NO_COLOR=1\` and a free port from the kernel, so two runs never share an instance. Run it from the repository root after installing dependencies.
419
+
420
+ ## Doctor
421
+
422
+ \`\`\`bash
423
+ ${BIN} doctor <run>
424
+ \`\`\`
425
+
426
+ Doctor checks that HEAD has not moved since \`new\`, \`ajs\` comes from the repository's \`@antelopejs/core\`, the build is newer than \`src/\`, what \`new\` prepared is there, and no process the run recorded is still alive. Do not drive a run that fails doctor.
427
+
428
+ ## Drive
429
+
430
+ \`\`\`bash
431
+ ${BIN} plan --base origin/main
432
+ ${BIN} journey <run> <feature> [journey...]
433
+ \`\`\`
434
+
435
+ \`plan\` maps the diff to features and lists unmapped surfaces. \`journey\` runs a feature's journeys, or the ones named. The pack ships these journeys for this kind; a feature file names them next to the repository's own:
436
+
437
+ ${text.builtins}
438
+
439
+ ## Evidence
440
+
441
+ Each step writes \`<run>/evidence/<feature>/<journey>/<NN-step>/\` with \`command.txt\`, \`stdout.txt\`, \`stderr.txt\`, \`exit-code.txt\`, \`pid.txt\` for background processes, \`tree.txt\`, \`http.json\` for every request, and \`checks.json\`. \`result.json\` holds a journey's result and \`feature.json\` the merged results of the feature. Read the evidence before you judge a PASS: a check proves only what it asserts.
442
+
443
+ ## Cleanup
444
+
445
+ \`\`\`bash
446
+ ${BIN} clean <run>
447
+ \`\`\`
448
+
449
+ \`clean\` stops what the run started, by recorded PID and container name, and removes everything but \`evidence/\` and \`run.json\`. Run it after every run, failed ones included.
450
+
451
+ ## The repository's own layer
452
+
453
+ - \`verify.config.ts\` default-exports a \`VerifyConfig\` from \`@antelopejs/tooling-configs/verify\`:
454
+ - \`doors\`: one entry per door kind (\`data\`, \`format\`, \`contract\`, \`outbound\`, \`exposure\`, \`publish\`), each \`null\` when it cannot apply or \`{ globs, funnels, containments, why }\`. \`containments\` names the \`feature/journey\` that contains a Data or Format door.
455
+ - \`journeys\`: the repository's journeys by id, each \`{ title, entryPoint, run(context) }\`, using the check helpers the same import exports.
456
+ - \`env\`, \`setup\` (commands replacing the build), \`userFacing\` (globs replacing the kind's default) and \`formal\` (formal checks with the files they cover).
457
+ ${text.layer}
458
+ - \`features/<feature>.md\`: frontmatter lists \`covers:\` (source globs), \`docs:\` (pages a verdict judges) and \`journeys:\`, then the sections Sub-features, How to get to it (user POV), Driving it with antelopejs-verify, and Gotchas. \`features/smoke.md\` covers nothing and runs on every verdict; here it runs ${text.smoke}.
459
+ - \`seeded-breaks/<feature>.patch\`: one minimal product bug per feature that its journeys must catch.
460
+ - \`seeded-doors/<kind>.patch\`: one change per door kind that applies.
461
+
462
+ \`\`\`bash
463
+ ${BIN} map
464
+ \`\`\`
465
+
466
+ \`map\` fails on a user-facing file no feature covers, a feature without journeys, docs or seeded break, an unknown journey, an applicable door kind without its seeded door, and a Data or Format door whose \`containments\` name no journey a feature registers.
467
+
468
+ ## Verdict rules
469
+
470
+ 1. **Run every feature whose \`covers:\` globs the diff touches, plus \`smoke\`.** \`plan\` prints that list as \`run\`.
471
+ 2. **An unmapped surface fails the verdict.** A changed user-facing file no feature covers needs a feature entry, its journeys and its seeded break in the same PR.
472
+ 3. **Every registered journey of a feature in \`run\` must have run and passed.** Run whole features. A journey that could not reach the product is not verified, and so is the verdict, never PASS.
473
+ 4. **Docs.** Judge every \`docs:\` page of a touched feature against what the journeys showed. A stale page fails the verdict.
474
+ 5. **Formal checks.** \`${BIN} formal <run>\` runs every formal check of \`verify.config.ts\` that covers the diff. One that did not run, violates a rule or errors fails the verdict.
475
+ 6. **One-way doors.** The section comes right after the result line and is mandatory. \`${BIN} doors\` prints the \`One-way-door:\` line of the diff. Every file the path rules flag needs a door row or a false positive with its reason. A Data or Format row names a \`containments\` journey that passed in this run.
476
+ 7. **Result.** FAIL if any rule fails. NOT VERIFIED when a journey could not reach the product. PASS+NOTES when something is not verified or needs the owner's attention. PASS otherwise.
477
+
478
+ Write your judgement to \`<run>/evidence/judgement.json\`:
479
+
480
+ \`\`\`json
481
+ {
482
+ "doors": {
483
+ "none": "why the diff opens no door",
484
+ "rows": [],
485
+ "falsePositives": [{ "kind": "publish", "location": "package.json", "reason": "only devDependencies changed" }]
486
+ },
487
+ "docs": [{ "page": "README.md", "matches": true, "note": "" }],
488
+ "notVerified": ["What no journey reached, and why"],
489
+ "attention": ["What the owner should look at that the journeys cannot judge"],
490
+ "verifier": "the fresh thread that judged this run, not the author"
491
+ }
492
+ \`\`\`
493
+
494
+ A door row is \`{ "kind", "location", "irreversible", "containment", "containmentJourney" }\`. Then render and publish:
495
+
496
+ \`\`\`bash
497
+ ${BIN} verdict <run> --pr <n>
498
+ ${BIN} publish <run> --pr <n>
499
+ \`\`\`
500
+
501
+ \`verdict\` writes \`evidence/verdict.md\` and exits 1 unless the result is PASS or PASS+NOTES. \`publish\` commits the evidence to the orphan branch \`verify-evidence\` under \`pr-<n>/<sha>/\` from a temporary worktree, posts the verdict as a PR comment, sets commit status \`verify\` on the head SHA (\`success\` for PASS and PASS+NOTES, \`error\` for NOT VERIFIED, \`failure\` for FAIL) and reads it back. It prints the error GitHub answers when the token cannot write statuses. A new push voids the status. Post a verdict only from a thread that did not write the change.
502
+
503
+ ## Trust
504
+
505
+ The skill is not Trusted yet. It becomes Trusted when it catches every seeded break and flags every seeded door, passes a shadow run of 10 consecutive agent PRs, and its last maintain pass is newer than the last change to the repository or its \`@antelopejs\` dependencies and at most 30 days old.
506
+
507
+ ## Seeded breaks and doors
508
+
509
+ \`\`\`bash
510
+ ${BIN} seeded <feature...>
511
+ ${BIN} seeded-doors
512
+ \`\`\`
513
+
514
+ \`seeded\` runs each feature's journeys in a scratch worktree of HEAD without the patch, as the control, and with \`seeded-breaks/<feature>.patch\` applied. It prints \`CAUGHT\` only when a journey that passes in the control fails one of its checks with the patch. Journeys failing in the control and failures without a failing check do not count. \`seeded-doors\` prints \`FLAGGED\` when the path rules flag each patch with its own kind.
515
+
516
+ ## Gotchas
517
+
518
+ ${bullets(text.gotchas)}
519
+ - Runs live under the system temp folder (\`TMPDIR\`), and the shared caches under \`~/.cache/antelopejs-verify\`.
520
+ - A repository that outgrows this skill runs \`antelopejs-sync --verify custom\` and keeps its own \`.agents/skills/verify-<repo>/\`.
521
+ `;
522
+ }
523
+ /** The skill folder's package.json: it makes verify.config.ts an ES module and keeps the folder out of published packages. */
524
+ const SKILL_PACKAGE = `${JSON.stringify({
525
+ private: true,
526
+ type: "module"
527
+ }, null, 2)}\n`;
528
+ /** Every file of a kind's synced layer, by path relative to the repository root. */
529
+ function syncedFiles(kind) {
530
+ return [{
531
+ path: `${skillFolder(kind)}/SKILL.md`,
532
+ content: skillText(kind)
533
+ }, {
534
+ path: `${skillFolder(kind)}/package.json`,
535
+ content: SKILL_PACKAGE
536
+ }];
537
+ }
538
+ //#endregion
539
+ //#region src/guardrails/verify-skill.ts
540
+ /** Whether `value` is a valid `--verify` argument. */
541
+ function isVerifyChoice(value) {
542
+ return value === "custom" || isVerifyKind(value);
543
+ }
544
+ const SKILL_DIRECTORIES = [
545
+ ".agents/skills",
546
+ ".claude/skills",
547
+ "skills"
548
+ ];
549
+ function skillPath(kind) {
550
+ return `${skillFolder(kind)}/SKILL.md`;
551
+ }
552
+ /** The repository's own verification skill: a folder named like `verif` with a SKILL.md, other than the shared kind folders. */
553
+ function ownVerificationSkill(root) {
554
+ const shared = VERIFY_KINDS.map(skillFolder);
555
+ for (const directory of SKILL_DIRECTORIES) {
556
+ if (!existsSync(join(root, directory))) continue;
557
+ for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
558
+ const folder = `${directory}/${entry.name}`;
559
+ if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && !shared.includes(folder) && existsSync(join(root, folder, "SKILL.md"))) return `${folder}/SKILL.md`;
560
+ }
561
+ }
562
+ }
563
+ function inferKind(manifest, profile) {
564
+ if (profile === "template") return "template";
565
+ const declared = manifest.antelopeJs;
566
+ if (declared?.kind === "interface" || declared?.kind === "module") return declared.kind;
567
+ if (Array.isArray(declared?.implements) && declared.implements.length > 0) return "module";
568
+ }
569
+ function resolveKind(root, flag, manifest, profile) {
570
+ const errors = [];
571
+ if (flag === "custom" && ownVerificationSkill(root) === void 0) errors.push("--verify custom needs your own verification skill: write it under .agents/skills/verify-<repo>/ first.");
572
+ if (flag !== void 0) return {
573
+ kind: flag,
574
+ errors
575
+ };
576
+ const synced = VERIFY_KINDS.filter((kind) => existsSync(join(root, skillPath(kind))));
577
+ if (synced.length > 1) return {
578
+ kind: void 0,
579
+ errors: [`Several shared verification skills exist: ${synced.map(skillPath).join(", ")}. Keep one: run antelopejs-sync --verify <kind>.`]
580
+ };
581
+ if (synced.length === 1) return {
582
+ kind: synced[0],
583
+ errors
584
+ };
585
+ if (ownVerificationSkill(root) !== void 0) return {
586
+ kind: "custom",
587
+ errors
588
+ };
589
+ return {
590
+ kind: inferKind(manifest, profile),
591
+ errors
592
+ };
593
+ }
594
+ function readIfPresent(root, path) {
595
+ const file = join(root, path);
596
+ return existsSync(file) ? readFileSync(file, "utf8") : void 0;
597
+ }
598
+ function planSharedKind(root, kind) {
599
+ const actions = [];
600
+ const errors = [];
601
+ for (const { path, content } of syncedFiles(kind)) if (lstatSync(join(root, path), { throwIfNoEntry: false })?.isDirectory()) errors.push(`${path} is a folder. Move it away, then rerun antelopejs-sync.`);
602
+ else if (readIfPresent(root, path) !== content) actions.push({
603
+ kind: "write",
604
+ path,
605
+ content
606
+ });
607
+ const link = claudeLink(kind);
608
+ const target = claudeLinkTarget(kind);
609
+ const stat = lstatSync(join(root, link), { throwIfNoEntry: false });
610
+ if (stat === void 0) actions.push({
611
+ kind: "link",
612
+ path: link,
613
+ target
614
+ });
615
+ else if (!stat.isSymbolicLink()) errors.push(`${link} is not a symlink. Move it away, then rerun antelopejs-sync.`);
616
+ else if (readlinkSync(join(root, link)) !== target) actions.push({
617
+ kind: "link",
618
+ path: link,
619
+ target
620
+ });
621
+ return {
622
+ actions,
623
+ errors
624
+ };
625
+ }
626
+ function planStaleKinds(root, keep) {
627
+ const actions = [];
628
+ const notes = [];
629
+ for (const kind of VERIFY_KINDS) {
630
+ if (kind === keep) continue;
631
+ const before = actions.length;
632
+ for (const { path } of syncedFiles(kind)) {
633
+ const synced = lstatSync(join(root, path), { throwIfNoEntry: false });
634
+ if (synced?.isFile() || synced?.isSymbolicLink()) actions.push({
635
+ kind: "remove",
636
+ path
637
+ });
638
+ }
639
+ if (lstatSync(join(root, claudeLink(kind)), { throwIfNoEntry: false })?.isSymbolicLink()) actions.push({
640
+ kind: "remove",
641
+ path: claudeLink(kind)
642
+ });
643
+ if (actions.length === before) continue;
644
+ const folder = skillFolder(kind);
645
+ const kept = existsSync(join(root, folder)) && readdirSync(join(root, folder)).some((name) => !syncedFiles(kind).some(({ path }) => path === `${folder}/${name}`));
646
+ notes.push(`Removed the synced files of verify-${kind}.${kept ? ` Kept its repo-owned files in ${folder}.` : ""}`);
647
+ }
648
+ return {
649
+ actions,
650
+ notes
651
+ };
652
+ }
653
+ /** Resolves the repository's verification kind and plans the synced layer; the repo-owned files are never touched. */
654
+ function planVerify(root, options) {
655
+ const { kind, errors } = resolveKind(root, options.flag, options.manifest, options.profile);
656
+ const shared = kind !== void 0 && kind !== "custom" ? kind : void 0;
657
+ const wanted = shared ? planSharedKind(root, shared) : {
658
+ actions: [],
659
+ errors: []
660
+ };
661
+ const stale = kind === void 0 ? {
662
+ actions: [],
663
+ notes: []
664
+ } : planStaleKinds(root, shared);
665
+ return {
666
+ kind,
667
+ verificationSkill: shared ? skillPath(shared) : ownVerificationSkill(root),
668
+ actions: [...wanted.actions, ...stale.actions],
669
+ errors: [...errors, ...wanted.errors],
670
+ notes: stale.notes
671
+ };
672
+ }
673
+ /** Applies planned changes; a replaced symlink is unlinked first so a write never goes through it. */
674
+ function applyVerifyActions(root, actions) {
675
+ for (const action of actions) {
676
+ const path = join(root, action.path);
677
+ if (action.kind === "remove") {
678
+ unlinkSync(path);
679
+ continue;
680
+ }
681
+ mkdirSync(dirname(path), { recursive: true });
682
+ if (lstatSync(path, { throwIfNoEntry: false }) !== void 0) unlinkSync(path);
683
+ if (action.kind === "write") writeFileSync(path, action.content);
684
+ else symlinkSync(action.target, path);
685
+ }
686
+ }
342
687
  //#endregion
343
688
  //#region src/guardrails/sync.ts
344
689
  const LEGACY_COMMENT_INSTRUCTION = "- Explain non-obvious constraints and decisions in comments; avoid restating the code. Document public contracts with TSDoc.";
@@ -491,19 +836,6 @@ function planSync(current, modes, context) {
491
836
  }
492
837
  return plan;
493
838
  }
494
- function verificationSkill(root) {
495
- for (const directory of [
496
- ".agents/skills",
497
- ".claude/skills",
498
- "skills"
499
- ]) {
500
- if (!existsSync(join(root, directory))) continue;
501
- for (const entry of readdirSync(join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
502
- const path = `${directory}/${entry.name}/SKILL.md`;
503
- if (entry.isDirectory() && entry.name.toLowerCase().includes("verif") && existsSync(join(root, path))) return path;
504
- }
505
- }
506
- }
507
839
  function repositorySnapshot(root) {
508
840
  const current = /* @__PURE__ */ new Map();
509
841
  const modes = /* @__PURE__ */ new Map();
@@ -529,7 +861,7 @@ function claudeProse(root, current) {
529
861
  if (!claude.includes("\n") && /^(?:@?(?:\.\/)?AGENTS\.md|(?:See |Refer to )?\[AGENTS\.md\]\((?:\.\/)?AGENTS\.md\)(?: for .*)?\.?)$/i.test(claude)) return "";
530
862
  return claude;
531
863
  }
532
- function repositoryContext(root, current, profile) {
864
+ function repositoryContext(root, current, profile, verificationSkill) {
533
865
  const manifest = parseManifest(current.get("package.json") ?? "{}");
534
866
  const lint = PRESET_CONFIGS[0];
535
867
  const desiredLint = current.get(lint.path) ?? lint.content;
@@ -546,7 +878,7 @@ function repositoryContext(root, current, profile) {
546
878
  suppressionBudget: profile === "full" && !current.has("guardrails.suppressions.json") ? adoptedBudget(root) : "",
547
879
  packageName: manifest.name ?? "",
548
880
  managesCi: current.has(".github/workflows/ci.yml") || !hasChecksWorkflow(root),
549
- verificationSkill: verificationSkill(root),
881
+ verificationSkill,
550
882
  glossary: ["GLOSSARY.md", "docs/GLOSSARY.md"].find((file) => existsSync(join(root, file)))
551
883
  };
552
884
  }
@@ -570,11 +902,16 @@ function syncRepository(root, options = {}) {
570
902
  const profile = options.profile ?? "full";
571
903
  const { current, modes } = repositorySnapshot(root);
572
904
  const manifest = parseManifest(current.get("package.json") ?? "{}");
573
- const context = repositoryContext(root, current, profile);
905
+ const verify = planVerify(root, {
906
+ flag: options.verify,
907
+ manifest,
908
+ profile
909
+ });
910
+ const context = repositoryContext(root, current, profile, verify.verificationSkill);
574
911
  let plan = planSync(current, modes, context);
575
912
  const errors = plan.filter((artifact) => artifact.kind === "error").map(({ message }) => message);
576
913
  const entryOnly = checkEntryOnlyConfiguration(root);
577
- errors.push(...entryOnly.errors);
914
+ errors.push(...entryOnly.errors, ...verify.errors);
578
915
  const notes = plan.flatMap((artifact) => artifact.kind === "migrated" ? artifact.notes : []);
579
916
  (options.check ? errors : notes).push(...repositoryNotices(root, context));
580
917
  if (!errors.length && profile === "full" && !options.check && !current.has("guardrails.ratchet.json") && manifest.scripts?.["sync:check"] === void 0) {
@@ -586,15 +923,19 @@ function syncRepository(root, options = {}) {
586
923
  plan = planSync(current, modes, context);
587
924
  }
588
925
  const writes = plan.filter((artifact) => artifact.kind === "write" || artifact.kind === "migrated");
589
- if (!options.check && !errors.length) writeArtifacts(root, writes);
926
+ if (!options.check && !errors.length) {
927
+ writeArtifacts(root, writes);
928
+ applyVerifyActions(root, verify.actions);
929
+ }
590
930
  const requiredDependencies = ["lefthook", "knip"];
591
931
  if (context.typeAware) requiredDependencies.push("oxlint-tsgolint");
592
932
  const dependenciesAdded = profile === "full" && requiredDependencies.some((name) => !manifest.devDependencies?.[name]);
593
933
  return {
594
934
  artifacts: plan,
595
- paths: errors.length ? [] : writes.map(({ path }) => path),
935
+ paths: errors.length ? [] : [...writes, ...verify.actions].map(({ path }) => path),
596
936
  errors,
597
937
  notes,
938
+ verifyNotes: verify.notes,
598
939
  advisories: entryOnly.advisories,
599
940
  dependenciesAdded
600
941
  };
@@ -607,14 +948,18 @@ runCli(() => {
607
948
  profile: {
608
949
  type: "string",
609
950
  default: "full"
610
- }
951
+ },
952
+ verify: { type: "string" }
611
953
  } });
612
954
  if (values.profile !== "full" && values.profile !== "template") throw new Error("--profile must be full or template.");
955
+ if (values.verify !== void 0 && !isVerifyChoice(values.verify)) throw new Error("--verify must be interface, module, template, or custom.");
613
956
  const result = syncRepository(repositoryRoot(), {
614
957
  check: values.check,
615
- profile: values.profile
958
+ profile: values.profile,
959
+ verify: values.verify
616
960
  });
617
961
  for (const note of result.notes) process.stdout.write(`Note: ${values.check || result.errors.length ? "Planned migration. " : ""}${note}\n`);
962
+ for (const note of result.verifyNotes) process.stdout.write(`Note: ${note}\n`);
618
963
  for (const advisory of result.advisories) process.stdout.write(`${advisory}\n`);
619
964
  for (const error of result.errors) process.stderr.write(`${error}\n`);
620
965
  if (result.errors.length) return 1;
@@ -0,0 +1 @@
1
+ export {}