@vaubaan/harness 1.4.0 → 2.1.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 (41) hide show
  1. package/README.md +301 -167
  2. package/dist/cli/index.js +886 -1882
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/handbook.cmd.md +4 -3
  5. package/dist/commands/test-plan.cmd.md +4 -4
  6. package/dist/index.d.ts +2 -2
  7. package/dist/index.js +277 -1064
  8. package/dist/index.js.map +1 -1
  9. package/dist/init.d.ts +8 -23
  10. package/dist/init.js +270 -1036
  11. package/dist/init.js.map +1 -1
  12. package/dist/linters/index.js +687 -31
  13. package/dist/linters/index.js.map +1 -1
  14. package/dist/parser/index.d.ts +1 -26
  15. package/dist/parser/index.js +1 -17
  16. package/dist/parser/index.js.map +1 -1
  17. package/dist/{render-Cu2XrkkY.d.ts → render-C-FWmUfX.d.ts} +8 -15
  18. package/dist/render.d.ts +1 -1
  19. package/dist/render.js +18 -280
  20. package/dist/render.js.map +1 -1
  21. package/dist/skills/decision-record-writer.skill.md +93 -131
  22. package/dist/skills/doc-audit.skill.md +10 -10
  23. package/dist/skills/drift-detector.skill.md +6 -7
  24. package/dist/skills/handbook-writer.skill.md +68 -159
  25. package/dist/skills/readme-writer.skill.md +3 -3
  26. package/dist/skills/spec-writer.skill.md +111 -71
  27. package/dist/skills/test-plan-writer.skill.md +47 -54
  28. package/dist/skills/workflow-writer.skill.md +40 -6
  29. package/dist/templates/code-quality.md.tmpl +2 -2
  30. package/dist/templates/coding-workflow.md.tmpl +10 -0
  31. package/dist/templates/decision.md.tmpl +20 -47
  32. package/dist/templates/e2e-tests.md.tmpl +16 -45
  33. package/dist/templates/handbook.md.tmpl +20 -38
  34. package/dist/templates/integration-tests.md.tmpl +16 -34
  35. package/package.json +1 -1
  36. package/dist/agents/coding.agent.md +0 -182
  37. package/dist/agents/merge.agent.md +0 -139
  38. package/dist/agents/planning.agent.md +0 -194
  39. package/dist/agents/review.agent.md +0 -176
  40. package/dist/commands/clean-code.cmd.md +0 -26
  41. package/dist/skills/clean-code-guardian.skill.md +0 -391
@@ -349,57 +349,712 @@ var frontmatterTracks = {
349
349
  }
350
350
  };
351
351
 
352
+ // src/linters/generated-fresh.ts
353
+ import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
354
+ import { join as join8, resolve as resolve4 } from "path";
355
+
356
+ // src/cli/managed-paths.ts
357
+ import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
358
+ import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join4, resolve as resolve2, win32 } from "path";
359
+ var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
360
+ var RELEASED_PATHS = [
361
+ ".mcp.json",
362
+ ".codex/config.toml",
363
+ ".opencode/opencode.json",
364
+ ".opencode/mcp.json",
365
+ ".claude/settings.json",
366
+ ".codex/hooks.json"
367
+ ];
368
+ var MANAGED_DIRECTORIES = [
369
+ ".claude/agents/",
370
+ ".claude/commands/",
371
+ ".claude/skills/",
372
+ ".codex/agents/",
373
+ ".codex/commands/",
374
+ ".codex/skills/",
375
+ ".agents/skills/",
376
+ ".opencode/agents/",
377
+ ".opencode/commands/",
378
+ ".opencode/skills/",
379
+ ".opencode/plugins/"
380
+ ];
381
+ function canonicalTargetRoot(root) {
382
+ let ancestor = resolve2(root);
383
+ const missing = [];
384
+ while (!lstatSync(ancestor, { throwIfNoEntry: false })) {
385
+ missing.unshift(basename(ancestor));
386
+ ancestor = dirname2(ancestor);
387
+ }
388
+ const canonical = realpathSync(ancestor);
389
+ if (!statSync2(canonical).isDirectory()) {
390
+ throw new Error(`harness target is not a directory: ${root}`);
391
+ }
392
+ return join4(canonical, ...missing);
393
+ }
394
+ function assertManagedLocation(path) {
395
+ const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
396
+ if (isAbsolute2(path) || win32.isAbsolute(path) || path.includes("\\") || path.includes("\0") || invalidSegment) {
397
+ throw new Error(`unsafe harness path: ${path}`);
398
+ }
399
+ if (!MANAGED_FILES.has(path) && !MANAGED_DIRECTORIES.some((prefix) => path.startsWith(prefix))) {
400
+ throw new Error(`path is outside harness-managed locations: ${path}`);
401
+ }
402
+ }
403
+ function assertNoSymbolicComponents(root, path) {
404
+ const parts = path.split("/");
405
+ let current = root;
406
+ for (const [index, part] of parts.entries()) {
407
+ current = join4(current, part);
408
+ const info = lstatSync(current, { throwIfNoEntry: false });
409
+ if (!info) return;
410
+ if (info.isSymbolicLink()) {
411
+ throw new Error(`symbolic link in harness path: ${path}`);
412
+ }
413
+ const isLeaf = index === parts.length - 1;
414
+ if (isLeaf ? !info.isFile() : !info.isDirectory()) {
415
+ throw new Error(`unexpected file type in harness path: ${path}`);
416
+ }
417
+ }
418
+ }
419
+ function assertManagedPaths(root, files) {
420
+ for (const path of files) assertManagedLocation(path);
421
+ const canonicalRoot = canonicalTargetRoot(root);
422
+ for (const path of files) assertNoSymbolicComponents(canonicalRoot, path);
423
+ }
424
+
425
+ // src/cli/manifest.ts
426
+ import { createHash } from "crypto";
427
+ import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
428
+ import { join as join5 } from "path";
429
+ import { z } from "zod";
430
+ var MANIFEST_FILENAME = ".harness-manifest.json";
431
+ var MANIFEST_VERSION = "6";
432
+ var ManifestSchema = z.object({
433
+ version: z.enum(["4", "5", MANIFEST_VERSION]),
434
+ engines: z.array(z.string()),
435
+ renderedAt: z.string(),
436
+ files: z.array(z.string()),
437
+ harnessVersion: z.string().optional(),
438
+ overridesDir: z.string().optional(),
439
+ fileHashes: z.record(z.string().regex(/^[a-f0-9]{64}$/)).optional(),
440
+ preservedFiles: z.array(z.string()).optional()
441
+ });
442
+ function manifestPath(targetDir) {
443
+ return join5(targetDir, MANIFEST_FILENAME);
444
+ }
445
+ function readManifest(targetDir) {
446
+ assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
447
+ const path = manifestPath(targetDir);
448
+ if (!existsSync4(path)) return null;
449
+ const raw = JSON.parse(readFileSync2(path, "utf8"));
450
+ return ManifestSchema.parse(raw);
451
+ }
452
+
453
+ // src/cli/plan-render.ts
454
+ import { existsSync as existsSync6 } from "fs";
455
+ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
456
+ import { fileURLToPath } from "url";
457
+
458
+ // src/loader.ts
459
+ import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
460
+ import { join as join6 } from "path";
461
+ import fg4 from "fast-glob";
462
+ import { z as z3 } from "zod";
463
+
464
+ // src/parser/common.ts
465
+ import { readFileSync as readFileSync3 } from "fs";
466
+ import matter2 from "gray-matter";
467
+
468
+ // src/parser/schemas.ts
469
+ import { z as z2 } from "zod";
470
+
471
+ // src/types.ts
472
+ var ENGINES = ["claude-code", "codex-cli", "opencode"];
473
+ var CAPABILITIES = ["multi-step", "slash-command", "inline-exec"];
474
+ var CAPABILITIES_MATRIX = {
475
+ "claude-code": ["multi-step", "slash-command", "inline-exec"],
476
+ "codex-cli": ["multi-step", "slash-command", "inline-exec"],
477
+ opencode: ["multi-step", "slash-command", "inline-exec"]
478
+ };
479
+ var DEGRADED_CAPABILITIES = {
480
+ "codex-cli": ["multi-step"]
481
+ };
482
+
483
+ // src/parser/schemas.ts
484
+ var IdSchema = z2.string().min(1).regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase + digits + hyphens)");
485
+ var SkillFrontmatterSchema = z2.object({
486
+ id: IdSchema,
487
+ description: z2.string().min(1),
488
+ engines: z2.array(z2.enum(ENGINES)).min(1).optional(),
489
+ requires: z2.array(z2.enum(CAPABILITIES)).optional(),
490
+ tags: z2.array(z2.string()).optional()
491
+ }).strict();
492
+ var CmdArgEnumSchema = z2.object({
493
+ name: z2.string().min(1),
494
+ type: z2.literal("enum"),
495
+ values: z2.array(z2.string()).min(1),
496
+ default: z2.string().optional()
497
+ }).strict();
498
+ var CmdArgStringSchema = z2.object({
499
+ name: z2.string().min(1),
500
+ type: z2.literal("string"),
501
+ default: z2.string().optional()
502
+ }).strict();
503
+ var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
504
+ var CmdFrontmatterSchema = z2.object({
505
+ id: IdSchema,
506
+ trigger: z2.string().regex(/^\/[a-z][a-z0-9-]*$/, "trigger must be /kebab-case"),
507
+ invokes_skill: IdSchema,
508
+ args: z2.array(CmdArgSchema).optional(),
509
+ description: z2.string().min(1)
510
+ }).strict();
511
+ var Schemas = {
512
+ Skill: SkillFrontmatterSchema,
513
+ Cmd: CmdFrontmatterSchema
514
+ };
515
+ var ParseError = class extends Error {
516
+ constructor(file, issues) {
517
+ const messages = issues.map((i) => ` - ${i.path.join(".") || "<root>"}: ${i.message}`).join("\n");
518
+ super(`Frontmatter validation failed for ${file}:
519
+ ${messages}`);
520
+ this.file = file;
521
+ this.issues = issues;
522
+ this.name = "ParseError";
523
+ }
524
+ file;
525
+ issues;
526
+ };
527
+
528
+ // src/parser/common.ts
529
+ function parseWithSchema(filePath, source, schema) {
530
+ const parsed = matter2(source);
531
+ const result = schema.safeParse(parsed.data);
532
+ if (!result.success) {
533
+ throw new ParseError(filePath, result.error.issues);
534
+ }
535
+ return {
536
+ meta: result.data,
537
+ body: parsed.content.trim(),
538
+ sourcePath: filePath
539
+ };
540
+ }
541
+
542
+ // src/parser/cmd.ts
543
+ function parseCmd(filePath, source) {
544
+ return parseWithSchema(filePath, source, Schemas.Cmd);
545
+ }
546
+
547
+ // src/parser/skill.ts
548
+ function parseSkill(filePath, source) {
549
+ return parseWithSchema(filePath, source, Schemas.Skill);
550
+ }
551
+
552
+ // src/util/yaml.ts
553
+ import { parse as yamlParse } from "yaml";
554
+ function parseYAML(source) {
555
+ return yamlParse(source);
556
+ }
557
+
558
+ // src/loader.ts
559
+ var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
560
+ function loadHarness(packageDir, opts = {}) {
561
+ const skillsDir = opts.skillsDir ?? join6(packageDir, "skills");
562
+ const commandsDir = opts.commandsDir ?? join6(packageDir, "commands");
563
+ const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
564
+ const cmdFiles = fg4.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
565
+ return {
566
+ skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
567
+ cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
568
+ };
569
+ }
570
+ function loadProjectSkills(targetDir) {
571
+ const skillsDir = join6(targetDir, "docs", "skills");
572
+ if (!existsSync5(skillsDir)) return [];
573
+ const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
574
+ return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
575
+ }
576
+ function loadOverrides(worktreeDir) {
577
+ const overridesDir = join6(worktreeDir, ".harness-overrides");
578
+ if (!existsSync5(overridesDir)) return void 0;
579
+ const added = loadHarness(overridesDir, {
580
+ skillsDir: join6(overridesDir, "skills"),
581
+ commandsDir: join6(overridesDir, "commands")
582
+ });
583
+ const disablePath = join6(overridesDir, "disable.yaml");
584
+ let disable = [];
585
+ if (existsSync5(disablePath)) {
586
+ try {
587
+ const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
588
+ if (parsed.success && parsed.data.disable) {
589
+ disable = parsed.data.disable;
590
+ }
591
+ } catch {
592
+ }
593
+ }
594
+ return { add: added, disable };
595
+ }
596
+
597
+ // src/renderers/common.ts
598
+ import { stringify as yamlStringify } from "yaml";
599
+ function checkSkillCapabilities(skill, engine) {
600
+ const blockingWarnings = [];
601
+ const degradedWarnings = [];
602
+ const supported = CAPABILITIES_MATRIX[engine];
603
+ const degraded = DEGRADED_CAPABILITIES[engine] ?? [];
604
+ if (!skill.meta.requires) return { blockingWarnings, degradedWarnings };
605
+ for (const cap of skill.meta.requires) {
606
+ if (!supported.includes(cap)) {
607
+ blockingWarnings.push(
608
+ `skill "${skill.meta.id}" requires "${cap}" not supported by "${engine}" \u2014 skipped`
609
+ );
610
+ } else if (degraded.includes(cap)) {
611
+ degradedWarnings.push(
612
+ `skill "${skill.meta.id}" requires "${cap}" \u2014 supported by "${engine}" with degradation`
613
+ );
614
+ }
615
+ }
616
+ return { blockingWarnings, degradedWarnings };
617
+ }
618
+ function isSkillEngineAllowed(skill, engine) {
619
+ if (!skill.meta.engines) return true;
620
+ return skill.meta.engines.includes(engine);
621
+ }
622
+ function yamlFrontmatter(data) {
623
+ const rendered = yamlStringify(data, { lineWidth: 0 }).trimEnd();
624
+ return `---
625
+ ${rendered}
626
+ ---
627
+ `;
628
+ }
629
+ function frontmatterDataForSkill(skill) {
630
+ const data = {
631
+ name: skill.meta.id,
632
+ description: skill.meta.description
633
+ };
634
+ if (skill.meta.tags && skill.meta.tags.length > 0) data.tags = skill.meta.tags;
635
+ return data;
636
+ }
637
+ function frontmatterDataForCmd(cmd) {
638
+ const data = {
639
+ id: cmd.meta.id,
640
+ trigger: cmd.meta.trigger,
641
+ description: cmd.meta.description
642
+ };
643
+ if (cmd.meta.args && cmd.meta.args.length > 0) {
644
+ data.args = cmd.meta.args.map((a) => {
645
+ if (a.type === "enum") {
646
+ return a.default !== void 0 ? { name: a.name, type: a.type, values: a.values, default: a.default } : { name: a.name, type: a.type, values: a.values };
647
+ }
648
+ return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
649
+ });
650
+ }
651
+ return data;
652
+ }
653
+ function buildUmbrellaBody(extras) {
654
+ const triggerBySkill = new Map(
655
+ extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
656
+ );
657
+ const skillLines = extras.availableSkills.map((s) => {
658
+ const trigger = triggerBySkill.get(s.meta.id);
659
+ const label = trigger ? `\`${s.meta.id}\` (\`${trigger}\`)` : `\`${s.meta.id}\``;
660
+ return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
661
+ });
662
+ const sections = [
663
+ "# How we work",
664
+ "",
665
+ "This file describes **how to work in this project**. The **business context** (what the project does, how to run it, which subsystems it contains) lives in `README.md` and `docs/`. Read them first.",
666
+ "",
667
+ "## Project map",
668
+ "",
669
+ "- `README.md` \u2014 pitch, quick start, scripts. Entry point.",
670
+ "- `docs/spec/<subsystem>.md` \u2014 *what* and *why* (tech-agnostic).",
671
+ "- `docs/handbook/<feature>.md` \u2014 what the code does not say: entry points, traps, settings outside the repo, manual procedures.",
672
+ "- `docs/decisions/<slug>.md` \u2014 ADRs: structural choices and rejected alternatives.",
673
+ "- `docs/tests/integration-tests.md` & `e2e-tests.md` \u2014 test scope, stack, conventions, known gaps.",
674
+ "- `docs/workflow/coding-workflow.md` \u2014 CI, branches, PR, release. How this team works: follow it.",
675
+ ...extras.hasProjectSkills ? ["- `docs/skills/*.skill.md` \u2014 the project's domain skills."] : [],
676
+ ...extras.hasQualityDoc ? [
677
+ "- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
678
+ ] : [],
679
+ "",
680
+ "## Doc-first",
681
+ "",
682
+ "The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
683
+ "",
684
+ "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
685
+ "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
686
+ "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
687
+ "- Suspected code \u2194 doc drift \u2192 `/drift` before moving on.",
688
+ "",
689
+ "## Checks",
690
+ "",
691
+ "Run `npx @vaubaan/harness lint` before you commit; CI runs the same linters on every pull request. Fix what it reports with the skill it suggests.",
692
+ "",
693
+ "The files the harness generates (`AGENTS.md`, `CLAUDE.md`, the `.claude/`, `.agents/` and `.opencode/` folders, `.harness-manifest.json`) are committed. Never edit them by hand: change their source in `docs/` or `.harness-overrides/`, run `npx @vaubaan/harness update .`, and commit the result. The linter fails when a generated file no longer matches its render."
694
+ ];
695
+ if (skillLines.length > 0) {
696
+ sections.push("", "## Doc-skills", "", skillLines.join("\n"));
697
+ }
698
+ return `${sections.join("\n")}
699
+ `;
700
+ }
701
+
702
+ // src/renderers/claude-code.ts
703
+ var ENGINE = "claude-code";
704
+ var BASE = ".claude";
705
+ var claudeCodeRenderer = {
706
+ engine: ENGINE,
707
+ renderSkill(skill) {
708
+ if (!isSkillEngineAllowed(skill, ENGINE)) {
709
+ return {
710
+ files: [],
711
+ warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE}"`]
712
+ };
713
+ }
714
+ const check = checkSkillCapabilities(skill, ENGINE);
715
+ if (check.blockingWarnings.length > 0) {
716
+ return { files: [], warnings: check.blockingWarnings };
717
+ }
718
+ const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
719
+ ${skill.body}
720
+ `;
721
+ return {
722
+ files: [{ path: `${BASE}/skills/${skill.meta.id}/SKILL.md`, content }],
723
+ warnings: check.degradedWarnings
724
+ };
725
+ },
726
+ renderCmd(cmd) {
727
+ const content = `${yamlFrontmatter(frontmatterDataForCmd(cmd))}
728
+ ${cmd.body}
729
+ `;
730
+ return {
731
+ files: [{ path: `${BASE}/commands/${cmd.meta.id}.md`, content }],
732
+ warnings: []
733
+ };
734
+ }
735
+ };
736
+
737
+ // src/renderers/codex-cli.ts
738
+ var ENGINE2 = "codex-cli";
739
+ var SKILLS_BASE = ".agents/skills";
740
+ var codexCliRenderer = {
741
+ engine: ENGINE2,
742
+ renderSkill(skill) {
743
+ if (!isSkillEngineAllowed(skill, ENGINE2)) {
744
+ return {
745
+ files: [],
746
+ warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE2}"`]
747
+ };
748
+ }
749
+ const check = checkSkillCapabilities(skill, ENGINE2);
750
+ if (check.blockingWarnings.length > 0) {
751
+ return { files: [], warnings: check.blockingWarnings };
752
+ }
753
+ const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
754
+ ${skill.body}
755
+ `;
756
+ return {
757
+ files: [{ path: `${SKILLS_BASE}/${skill.meta.id}/SKILL.md`, content }],
758
+ warnings: check.degradedWarnings
759
+ };
760
+ },
761
+ // Codex custom prompts are deprecated in favour of skills: nothing to render.
762
+ renderCmd(_cmd) {
763
+ return { files: [], warnings: [] };
764
+ }
765
+ };
766
+
767
+ // src/renderers/opencode.ts
768
+ var ENGINE3 = "opencode";
769
+ var BASE2 = ".opencode";
770
+ var opencodeRenderer = {
771
+ engine: ENGINE3,
772
+ renderSkill(skill) {
773
+ if (!isSkillEngineAllowed(skill, ENGINE3)) {
774
+ return {
775
+ files: [],
776
+ warnings: [`skill "${skill.meta.id}" excluded from engine "${ENGINE3}"`]
777
+ };
778
+ }
779
+ const check = checkSkillCapabilities(skill, ENGINE3);
780
+ if (check.blockingWarnings.length > 0) {
781
+ return { files: [], warnings: check.blockingWarnings };
782
+ }
783
+ const content = `${yamlFrontmatter(frontmatterDataForSkill(skill))}
784
+ ${skill.body}
785
+ `;
786
+ return {
787
+ files: [{ path: `${BASE2}/skills/${skill.meta.id}/SKILL.md`, content }],
788
+ warnings: check.degradedWarnings
789
+ };
790
+ },
791
+ renderCmd(cmd) {
792
+ const content = `${yamlFrontmatter({ description: cmd.meta.description })}
793
+ ${cmd.body}
794
+ `;
795
+ return {
796
+ files: [{ path: `${BASE2}/commands/${cmd.meta.id}.md`, content }],
797
+ warnings: []
798
+ };
799
+ }
800
+ };
801
+
802
+ // src/renderers/index.ts
803
+ var RENDERERS = {
804
+ "claude-code": claudeCodeRenderer,
805
+ "codex-cli": codexCliRenderer,
806
+ opencode: opencodeRenderer
807
+ };
808
+ function getRenderer(engine) {
809
+ return RENDERERS[engine];
810
+ }
811
+
812
+ // src/render.ts
813
+ var RenderError = class extends Error {
814
+ constructor(message) {
815
+ super(message);
816
+ this.name = "RenderError";
817
+ }
818
+ };
819
+ function mergeById(stock, added) {
820
+ const result = /* @__PURE__ */ new Map();
821
+ for (const item of stock) result.set(item.meta.id, item);
822
+ if (added) {
823
+ for (const item of added) result.set(item.meta.id, item);
824
+ }
825
+ return Array.from(result.values());
826
+ }
827
+ function removeByIds(items, disabled) {
828
+ if (disabled.length === 0) return [...items];
829
+ const disabledSet = new Set(disabled);
830
+ return items.filter((item) => !disabledSet.has(item.meta.id));
831
+ }
832
+ function applyOverrides(harness, overrides) {
833
+ const disabled = overrides?.disable ?? [];
834
+ return {
835
+ skills: removeByIds(mergeById(harness.skills, overrides?.add?.skills), disabled),
836
+ cmds: removeByIds(mergeById(harness.cmds, overrides?.add?.cmds), disabled)
837
+ };
838
+ }
839
+ var CLAUDE_MD_STUB = "@AGENTS.md\n";
840
+ function opencodeLast(engines) {
841
+ return [...engines].sort((a, b) => Number(a === "opencode") - Number(b === "opencode"));
842
+ }
843
+ function render(input) {
844
+ const { engines } = input;
845
+ if (engines.length === 0) {
846
+ throw new RenderError("at least one engine must be selected");
847
+ }
848
+ const base = input.projectSkills?.length ? { ...input.harness, skills: mergeById(input.harness.skills, input.projectSkills) } : input.harness;
849
+ const harness = applyOverrides(base, input.overrides);
850
+ const files = [];
851
+ const warnings = [];
852
+ const exposedSkills = /* @__PURE__ */ new Map();
853
+ const exposedCmds = /* @__PURE__ */ new Map();
854
+ for (const engine of opencodeLast(engines)) {
855
+ const renderer = getRenderer(engine);
856
+ const renderedSkillIds = /* @__PURE__ */ new Set();
857
+ for (const skill of harness.skills) {
858
+ const result = renderer.renderSkill(skill);
859
+ warnings.push(...result.warnings);
860
+ if (result.files.length > 0) {
861
+ const alreadyVisible = engine === "opencode" && exposedSkills.has(skill.meta.id);
862
+ if (!alreadyVisible) files.push(...result.files);
863
+ renderedSkillIds.add(skill.meta.id);
864
+ exposedSkills.set(skill.meta.id, skill);
865
+ }
866
+ }
867
+ for (const cmd of harness.cmds) {
868
+ if (!renderedSkillIds.has(cmd.meta.invokes_skill)) continue;
869
+ const result = renderer.renderCmd(cmd);
870
+ warnings.push(...result.warnings);
871
+ if (result.files.length > 0) {
872
+ files.push(...result.files);
873
+ exposedCmds.set(cmd.meta.id, cmd);
874
+ }
875
+ }
876
+ }
877
+ const umbrellaContent = buildUmbrellaBody({
878
+ availableSkills: Array.from(exposedSkills.values()),
879
+ availableCommands: Array.from(exposedCmds.values()),
880
+ hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
881
+ hasQualityDoc: input.hasQualityDoc === true
882
+ });
883
+ files.push({ path: "AGENTS.md", content: umbrellaContent });
884
+ if (engines.includes("claude-code")) {
885
+ files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
886
+ }
887
+ return { files, warnings };
888
+ }
889
+
890
+ // src/cli/plan-render.ts
891
+ var QUALITY_DOC_PATH = "docs/quality/code-quality.md";
892
+ function resolveEngineList(requested) {
893
+ if (!requested || requested.length === 0) {
894
+ throw new Error(
895
+ `no engine selected: pass --engines=<list> with one or more of ${ENGINES.join(", ")}`
896
+ );
897
+ }
898
+ const engines = requested.map((e) => {
899
+ if (!ENGINES.includes(e)) {
900
+ throw new Error(`unknown engine: ${e} (expected one of ${ENGINES.join(", ")})`);
901
+ }
902
+ return e;
903
+ });
904
+ return [...new Set(engines)];
905
+ }
906
+ function defaultPackageDir() {
907
+ const here = dirname3(fileURLToPath(import.meta.url));
908
+ if (existsSync6(join7(here, "skills"))) return here;
909
+ return resolve3(here, "..");
910
+ }
911
+ function planInit(args) {
912
+ const engines = resolveEngineList(args.engines);
913
+ const packageDir = args.packageDir ?? defaultPackageDir();
914
+ const harness = loadHarness(packageDir);
915
+ const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
916
+ const projectSkills = loadProjectSkills(args.targetDir);
917
+ const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
918
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
919
+ return { engines, output };
920
+ }
921
+
922
+ // src/linters/generated-fresh.ts
923
+ var FIX = "run `npx @vaubaan/harness update .` and commit the result";
924
+ var generatedFresh = {
925
+ id: "lint:generated-fresh",
926
+ pillars: ["repo-root"],
927
+ defaultSeverity: "error",
928
+ run(repoRoot) {
929
+ const issue = (file, message) => ({
930
+ linter: this.id,
931
+ severity: "error",
932
+ file,
933
+ message
934
+ });
935
+ let manifest;
936
+ try {
937
+ manifest = readManifest(repoRoot);
938
+ } catch (error) {
939
+ const reason = error instanceof Error ? error.message : String(error);
940
+ return [issue(".harness-manifest.json", `invalid harness manifest: ${reason}`)];
941
+ }
942
+ if (!manifest) return [];
943
+ const overridesParent = manifest.overridesDir ? resolve4(repoRoot, manifest.overridesDir) : repoRoot;
944
+ const hasOverrides = existsSync7(join8(overridesParent, ".harness-overrides"));
945
+ let rendered;
946
+ try {
947
+ rendered = planInit({
948
+ targetDir: repoRoot,
949
+ engines: manifest.engines,
950
+ overridesDir: hasOverrides ? overridesParent : void 0
951
+ });
952
+ } catch (error) {
953
+ const reason = error instanceof Error ? error.message : String(error);
954
+ return [issue(".harness-manifest.json", `cannot render the harness: ${reason}`)];
955
+ }
956
+ const preserved = new Set(manifest.preservedFiles ?? []);
957
+ const issues = [];
958
+ const renderedPaths = /* @__PURE__ */ new Set();
959
+ for (const file of rendered.output.files) {
960
+ if (preserved.has(file.path)) continue;
961
+ renderedPaths.add(file.path);
962
+ const full = join8(repoRoot, file.path);
963
+ if (!existsSync7(full)) {
964
+ issues.push(issue(file.path, `generated file is missing; ${FIX}`));
965
+ } else if (readFileSync5(full, "utf8") !== file.content) {
966
+ issues.push(
967
+ issue(
968
+ file.path,
969
+ `generated file differs from the current render; edit its source in docs/ or .harness-overrides/, then ${FIX}`
970
+ )
971
+ );
972
+ }
973
+ }
974
+ for (const path of manifest.files) {
975
+ if (renderedPaths.has(path) || preserved.has(path) || RELEASED_PATHS.includes(path)) continue;
976
+ if (existsSync7(join8(repoRoot, path))) {
977
+ issues.push(issue(path, `stale generated file, no longer rendered; ${FIX}`));
978
+ }
979
+ }
980
+ return issues;
981
+ }
982
+ };
983
+
352
984
  // src/linters/gitignore-harness.ts
353
985
  var REQUIRED_GITIGNORE_ENTRIES = [
354
986
  ".harness-overrides/",
355
- ".harness-manifest.json",
356
- ".harness/",
987
+ ".vaubaan/"
988
+ ];
989
+ var FORBIDDEN_GITIGNORE_ENTRIES = [
990
+ "AGENTS.md",
991
+ "CLAUDE.md",
357
992
  ".claude/",
358
993
  ".codex/",
359
- ".opencode/",
360
994
  ".agents/",
361
- ".vaubaan/",
362
- "AGENTS.md",
363
- "CLAUDE.md",
364
- ".mcp.json"
995
+ ".opencode/",
996
+ ".harness-manifest.json"
365
997
  ];
998
+ function gitignoreEntries(text) {
999
+ const entries = /* @__PURE__ */ new Set();
1000
+ for (const raw of text.split("\n")) {
1001
+ const line = raw.trim();
1002
+ if (!line || line.startsWith("#")) continue;
1003
+ entries.add(line.replace(/^\//, "").replace(/\/$/, ""));
1004
+ }
1005
+ return entries;
1006
+ }
1007
+ function normalize(entry) {
1008
+ return entry.replace(/\/$/, "");
1009
+ }
1010
+ function missingGitignoreEntries(text) {
1011
+ const lines = gitignoreEntries(text);
1012
+ return REQUIRED_GITIGNORE_ENTRIES.filter((entry) => !lines.has(normalize(entry)));
1013
+ }
1014
+ function forbiddenGitignoreEntries(text) {
1015
+ const lines = gitignoreEntries(text);
1016
+ return FORBIDDEN_GITIGNORE_ENTRIES.filter((entry) => lines.has(normalize(entry)));
1017
+ }
366
1018
  var gitignoreHarness = {
367
1019
  id: "lint:gitignore-harness",
368
1020
  pillars: ["repo-root"],
369
1021
  defaultSeverity: "error",
370
1022
  run(repoRoot) {
371
- const issues = [];
372
1023
  if (!fileExists(repoRoot, ".gitignore")) {
1024
+ return [
1025
+ {
1026
+ linter: this.id,
1027
+ severity: "error",
1028
+ file: ".gitignore",
1029
+ message: ".gitignore is missing at repo root"
1030
+ }
1031
+ ];
1032
+ }
1033
+ const text = readText(repoRoot, ".gitignore");
1034
+ const issues = [];
1035
+ for (const entry of missingGitignoreEntries(text)) {
373
1036
  issues.push({
374
1037
  linter: this.id,
375
1038
  severity: "error",
376
1039
  file: ".gitignore",
377
- message: ".gitignore is missing at repo root"
1040
+ message: `.gitignore must contain "${entry}"`
378
1041
  });
379
- return issues;
380
1042
  }
381
- const text = readText(repoRoot, ".gitignore");
382
- const lines = new Set(
383
- text.split("\n").map((l) => l.trim()).filter(Boolean)
384
- );
385
- for (const entry of REQUIRED_GITIGNORE_ENTRIES) {
386
- const variants = [entry, entry.replace(/\/$/, "")];
387
- if (!variants.some((v) => lines.has(v))) {
388
- issues.push({
389
- linter: this.id,
390
- severity: "error",
391
- file: ".gitignore",
392
- message: `.gitignore must contain "${entry}"`
393
- });
394
- }
1043
+ for (const entry of forbiddenGitignoreEntries(text)) {
1044
+ issues.push({
1045
+ linter: this.id,
1046
+ severity: "error",
1047
+ file: ".gitignore",
1048
+ message: `.gitignore must not contain "${entry}": files the harness generates are committed`
1049
+ });
395
1050
  }
396
1051
  return issues;
397
1052
  }
398
1053
  };
399
1054
 
400
1055
  // src/linters/orphan-decisions.ts
401
- import { basename } from "path";
402
- import fg4 from "fast-glob";
1056
+ import { basename as basename2 } from "path";
1057
+ import fg5 from "fast-glob";
403
1058
  var orphanDecisions = {
404
1059
  id: "lint:orphan-decisions",
405
1060
  pillars: ["decisions"],
@@ -410,7 +1065,7 @@ var orphanDecisions = {
410
1065
  const issues = [];
411
1066
  const adrs = listMarkdown(repoRoot, "docs/decisions");
412
1067
  if (adrs.length === 0) return issues;
413
- const otherDocs = fg4.sync("**/*.md", {
1068
+ const otherDocs = fg5.sync("**/*.md", {
414
1069
  cwd: repoRoot,
415
1070
  absolute: false,
416
1071
  ignore: [
@@ -427,7 +1082,7 @@ var orphanDecisions = {
427
1082
  });
428
1083
  const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
429
1084
  for (const adr of adrs) {
430
- const filename = basename(adr);
1085
+ const filename = basename2(adr);
431
1086
  const stem = filename.replace(/\.md$/, "");
432
1087
  const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
433
1088
  if (!referenced) {
@@ -603,12 +1258,12 @@ var specTechAgnostic = {
603
1258
  };
604
1259
 
605
1260
  // src/linters/tracks-drift.ts
606
- import fg5 from "fast-glob";
1261
+ import fg6 from "fast-glob";
607
1262
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
608
1263
  var DEFAULT_DRIFT_THRESHOLD = 10;
609
1264
  function expandGlob(repoRoot, pattern) {
610
1265
  if (pattern.includes("*")) {
611
- return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
1266
+ return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
612
1267
  }
613
1268
  return [pattern];
614
1269
  }
@@ -665,7 +1320,8 @@ var ALL_LINTERS = [
665
1320
  crossLinks,
666
1321
  orphanDecisions,
667
1322
  gitignoreHarness,
668
- qualitySchema
1323
+ qualitySchema,
1324
+ generatedFresh
669
1325
  ];
670
1326
  function runLinters(repoRoot, opts = {}) {
671
1327
  const config = loadLintConfig(repoRoot);