@vaubaan/harness 2.1.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -10,6 +10,12 @@ function fileExists(repoRoot, relativePath) {
10
10
  function readText(repoRoot, relativePath) {
11
11
  return readFileSync(join(repoRoot, relativePath), "utf8");
12
12
  }
13
+ function trackedPathExists(repoRoot, pattern) {
14
+ if (pattern.includes("*")) {
15
+ return fg.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
16
+ }
17
+ return existsSync(join(repoRoot, pattern));
18
+ }
13
19
  function listMarkdown(repoRoot, dir) {
14
20
  const cwd = join(repoRoot, dir);
15
21
  if (!existsSync(cwd)) return [];
@@ -293,16 +299,7 @@ var docLayout = {
293
299
  };
294
300
 
295
301
  // src/linters/frontmatter-tracks.ts
296
- import { existsSync as existsSync3 } from "fs";
297
- import { join as join3 } from "path";
298
- import fg3 from "fast-glob";
299
302
  var TRACKED_DIRS = ["docs/handbook", "docs/tests", "docs/workflow"];
300
- function trackedPathExists(repoRoot, pattern) {
301
- if (pattern.includes("*")) {
302
- return fg3.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
303
- }
304
- return existsSync3(join3(repoRoot, pattern));
305
- }
306
303
  var frontmatterTracks = {
307
304
  id: "lint:frontmatter-tracks",
308
305
  pillars: ["handbook", "tests", "workflow"],
@@ -350,13 +347,19 @@ var frontmatterTracks = {
350
347
  };
351
348
 
352
349
  // src/linters/generated-fresh.ts
353
- import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
350
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
354
351
  import { join as join8, resolve as resolve4 } from "path";
355
352
 
356
353
  // src/cli/managed-paths.ts
357
354
  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"]);
355
+ import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2, win32 } from "path";
356
+ var MANAGED_FILES = /* @__PURE__ */ new Set([
357
+ "AGENTS.md",
358
+ "CLAUDE.md",
359
+ ".harness-manifest.json",
360
+ // Index of the optional journeys pillar, rendered while a journey exists.
361
+ "docs/journeys/README.md"
362
+ ]);
360
363
  var RELEASED_PATHS = [
361
364
  ".mcp.json",
362
365
  ".codex/config.toml",
@@ -389,7 +392,7 @@ function canonicalTargetRoot(root) {
389
392
  if (!statSync2(canonical).isDirectory()) {
390
393
  throw new Error(`harness target is not a directory: ${root}`);
391
394
  }
392
- return join4(canonical, ...missing);
395
+ return join3(canonical, ...missing);
393
396
  }
394
397
  function assertManagedLocation(path) {
395
398
  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
@@ -404,7 +407,7 @@ function assertNoSymbolicComponents(root, path) {
404
407
  const parts = path.split("/");
405
408
  let current = root;
406
409
  for (const [index, part] of parts.entries()) {
407
- current = join4(current, part);
410
+ current = join3(current, part);
408
411
  const info = lstatSync(current, { throwIfNoEntry: false });
409
412
  if (!info) return;
410
413
  if (info.isSymbolicLink()) {
@@ -424,8 +427,8 @@ function assertManagedPaths(root, files) {
424
427
 
425
428
  // src/cli/manifest.ts
426
429
  import { createHash } from "crypto";
427
- import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
428
- import { join as join5 } from "path";
430
+ import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
431
+ import { join as join4 } from "path";
429
432
  import { z } from "zod";
430
433
  var MANIFEST_FILENAME = ".harness-manifest.json";
431
434
  var MANIFEST_VERSION = "6";
@@ -440,12 +443,12 @@ var ManifestSchema = z.object({
440
443
  preservedFiles: z.array(z.string()).optional()
441
444
  });
442
445
  function manifestPath(targetDir) {
443
- return join5(targetDir, MANIFEST_FILENAME);
446
+ return join4(targetDir, MANIFEST_FILENAME);
444
447
  }
445
448
  function readManifest(targetDir) {
446
449
  assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
447
450
  const path = manifestPath(targetDir);
448
- if (!existsSync4(path)) return null;
451
+ if (!existsSync3(path)) return null;
449
452
  const raw = JSON.parse(readFileSync2(path, "utf8"));
450
453
  return ManifestSchema.parse(raw);
451
454
  }
@@ -456,9 +459,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
456
459
  import { fileURLToPath } from "url";
457
460
 
458
461
  // 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 { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
463
+ import { join as join5 } from "path";
464
+ import fg3 from "fast-glob";
462
465
  import { z as z3 } from "zod";
463
466
 
464
467
  // src/parser/common.ts
@@ -508,9 +511,18 @@ var CmdFrontmatterSchema = z2.object({
508
511
  args: z2.array(CmdArgSchema).optional(),
509
512
  description: z2.string().min(1)
510
513
  }).strict();
514
+ var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
515
+ var JourneyFrontmatterSchema = z2.object({
516
+ title: z2.string().min(1),
517
+ status: z2.enum(JOURNEY_STATUSES),
518
+ actors: z2.array(z2.string().min(1)).min(1),
519
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
520
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
521
+ }).strict();
511
522
  var Schemas = {
512
523
  Skill: SkillFrontmatterSchema,
513
- Cmd: CmdFrontmatterSchema
524
+ Cmd: CmdFrontmatterSchema,
525
+ Journey: JourneyFrontmatterSchema
514
526
  };
515
527
  var ParseError = class extends Error {
516
528
  constructor(file, issues) {
@@ -558,31 +570,31 @@ function parseYAML(source) {
558
570
  // src/loader.ts
559
571
  var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
560
572
  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 });
573
+ const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
574
+ const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
575
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
576
+ const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
565
577
  return {
566
578
  skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
567
579
  cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
568
580
  };
569
581
  }
570
582
  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 });
583
+ const skillsDir = join5(targetDir, "docs", "skills");
584
+ if (!existsSync4(skillsDir)) return [];
585
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
574
586
  return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
575
587
  }
576
588
  function loadOverrides(worktreeDir) {
577
- const overridesDir = join6(worktreeDir, ".harness-overrides");
578
- if (!existsSync5(overridesDir)) return void 0;
589
+ const overridesDir = join5(worktreeDir, ".harness-overrides");
590
+ if (!existsSync4(overridesDir)) return void 0;
579
591
  const added = loadHarness(overridesDir, {
580
- skillsDir: join6(overridesDir, "skills"),
581
- commandsDir: join6(overridesDir, "commands")
592
+ skillsDir: join5(overridesDir, "skills"),
593
+ commandsDir: join5(overridesDir, "commands")
582
594
  });
583
- const disablePath = join6(overridesDir, "disable.yaml");
595
+ const disablePath = join5(overridesDir, "disable.yaml");
584
596
  let disable = [];
585
- if (existsSync5(disablePath)) {
597
+ if (existsSync4(disablePath)) {
586
598
  try {
587
599
  const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
588
600
  if (parsed.success && parsed.data.disable) {
@@ -594,6 +606,214 @@ function loadOverrides(worktreeDir) {
594
606
  return { add: added, disable };
595
607
  }
596
608
 
609
+ // src/parser/journey.ts
610
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
611
+ import { basename as basename2, join as join6 } from "path";
612
+ import matter3 from "gray-matter";
613
+ var JOURNEYS_DIR = "docs/journeys";
614
+ var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
615
+ var NODE_FIELDS = [
616
+ "status",
617
+ "spec",
618
+ "anchors",
619
+ "acceptance",
620
+ "requires",
621
+ "creates"
622
+ ];
623
+ var LEAF_FIELDS = [
624
+ "anchors",
625
+ "acceptance",
626
+ "requires",
627
+ "creates"
628
+ ];
629
+ var MASKED_LINE = "\0";
630
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
631
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
632
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
633
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
634
+ function maskFencedCode(lines) {
635
+ let fence;
636
+ return lines.map((line) => {
637
+ const m = FENCE_RE.exec(line);
638
+ if (fence !== void 0) {
639
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
640
+ return MASKED_LINE;
641
+ }
642
+ if (m?.[1]) {
643
+ fence = m[1];
644
+ return MASKED_LINE;
645
+ }
646
+ return line;
647
+ });
648
+ }
649
+ function parseHeading(line) {
650
+ const m = HEADING_RE.exec(line);
651
+ if (!m?.[1] || !m[2]) return void 0;
652
+ return { depth: m[1].length, title: m[2] };
653
+ }
654
+ function splitList(value) {
655
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
656
+ }
657
+ function bodyStart(lines) {
658
+ if (lines[0]?.trim() !== "---") return 0;
659
+ for (let i = 1; i < lines.length; i++) {
660
+ const l = lines[i]?.trim();
661
+ if (l === "---" || l === "...") return i + 1;
662
+ }
663
+ return lines.length;
664
+ }
665
+ function parseFrontmatter2(text, errors) {
666
+ let data;
667
+ try {
668
+ data = matter3(text).data;
669
+ } catch (error) {
670
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
671
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
672
+ return void 0;
673
+ }
674
+ const result = Schemas.Journey.safeParse(data);
675
+ if (result.success) return result.data;
676
+ for (const issue of result.error.issues) {
677
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
678
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
679
+ }
680
+ return void 0;
681
+ }
682
+ function newNode(title, level, line) {
683
+ return {
684
+ title,
685
+ level,
686
+ line,
687
+ isLeaf: true,
688
+ fieldLines: {},
689
+ anchors: [],
690
+ acceptance: [],
691
+ requires: [],
692
+ creates: [],
693
+ unknownFields: []
694
+ };
695
+ }
696
+ function parseFields(node, lines, from, to, errors) {
697
+ let lastKey;
698
+ for (let i = from; i < to; i++) {
699
+ const line = lines[i] ?? "";
700
+ if (line.trim() === "") continue;
701
+ const lineNo = i + 1;
702
+ const field = FIELD_RE.exec(line.trimEnd());
703
+ if (field?.[1] !== void 0) {
704
+ const key = field[1];
705
+ const value = (field[2] ?? "").trim();
706
+ lastKey = key;
707
+ if (!NODE_FIELDS.includes(key)) {
708
+ node.unknownFields.push({ key, line: lineNo });
709
+ continue;
710
+ }
711
+ const known = key;
712
+ node.fieldLines[known] = lineNo;
713
+ if (known === "status") {
714
+ if (JOURNEY_STATUSES.includes(value)) {
715
+ node.status = value;
716
+ } else {
717
+ errors.push({
718
+ line: lineNo,
719
+ message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
720
+ });
721
+ }
722
+ } else if (known === "spec") {
723
+ node.spec = value;
724
+ } else if (known === "acceptance") {
725
+ if (value) node.acceptance.push(value);
726
+ } else {
727
+ node[known] = splitList(value);
728
+ }
729
+ continue;
730
+ }
731
+ const item = LIST_ITEM_RE.exec(line);
732
+ if (lastKey === "acceptance" && item) {
733
+ const text = (item[1] ?? "").trim();
734
+ if (text) node.acceptance.push(text);
735
+ continue;
736
+ }
737
+ return;
738
+ }
739
+ }
740
+ function parseJourney(relPath, text) {
741
+ const errors = [];
742
+ const meta = parseFrontmatter2(text, errors);
743
+ const lines = maskFencedCode(text.split(/\r?\n/));
744
+ const start = bodyStart(lines);
745
+ const headings = [];
746
+ for (let i = start; i < lines.length; i++) {
747
+ const h = parseHeading(lines[i] ?? "");
748
+ if (h) headings.push({ index: i, ...h });
749
+ }
750
+ const h1 = headings.find((h) => h.depth === 1);
751
+ let story;
752
+ if (h1) {
753
+ const paragraph = [];
754
+ for (let i = h1.index + 1; i < lines.length; i++) {
755
+ const line = lines[i] ?? "";
756
+ if (line.trim() === "") {
757
+ if (paragraph.length) break;
758
+ continue;
759
+ }
760
+ if (line === MASKED_LINE || parseHeading(line)) break;
761
+ paragraph.push(line.trim());
762
+ }
763
+ if (paragraph.length) story = paragraph.join(" ");
764
+ }
765
+ const nodes = [];
766
+ const stack = [];
767
+ for (const [k, h] of headings.entries()) {
768
+ if (h.depth < 2) continue;
769
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
770
+ while (stack.length) {
771
+ const top = nodes[stack[stack.length - 1]];
772
+ if (top && top.level < node.level) break;
773
+ stack.pop();
774
+ }
775
+ const parentIndex = stack[stack.length - 1];
776
+ if (parentIndex !== void 0) {
777
+ node.parent = parentIndex;
778
+ const parent = nodes[parentIndex];
779
+ if (parent) parent.isLeaf = false;
780
+ }
781
+ const next = headings[k + 1];
782
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
783
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
784
+ node.effectiveStatus = node.status ?? inherited;
785
+ stack.push(nodes.length);
786
+ nodes.push(node);
787
+ }
788
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
789
+ return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
790
+ }
791
+ function listJourneyFiles(targetDir) {
792
+ const dir = join6(targetDir, JOURNEYS_DIR);
793
+ if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
794
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
795
+ }
796
+ function readJourneys(targetDir) {
797
+ return listJourneyFiles(targetDir).map((file) => {
798
+ const path = `${JOURNEYS_DIR}/${file}`;
799
+ const text = readFileSync5(join6(targetDir, path), "utf8");
800
+ return { path, file, ...parseJourney(path, text) };
801
+ });
802
+ }
803
+ function loadJourneys(targetDir) {
804
+ const journeys = readJourneys(targetDir);
805
+ const problems = journeys.flatMap(
806
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
807
+ );
808
+ if (problems.length) {
809
+ throw new Error(
810
+ `invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
811
+ ${problems.join("\n")}`
812
+ );
813
+ }
814
+ return journeys;
815
+ }
816
+
597
817
  // src/renderers/common.ts
598
818
  import { stringify as yamlStringify } from "yaml";
599
819
  function checkSkillCapabilities(skill, engine) {
@@ -651,12 +871,15 @@ function frontmatterDataForCmd(cmd) {
651
871
  return data;
652
872
  }
653
873
  function buildUmbrellaBody(extras) {
654
- const triggerBySkill = new Map(
655
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
656
- );
874
+ const triggersBySkill = /* @__PURE__ */ new Map();
875
+ for (const c of extras.availableCommands) {
876
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
877
+ triggers.push(c.meta.trigger);
878
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
879
+ }
657
880
  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}\``;
881
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
882
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
660
883
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
661
884
  });
662
885
  const sections = [
@@ -676,11 +899,17 @@ function buildUmbrellaBody(extras) {
676
899
  ...extras.hasQualityDoc ? [
677
900
  "- `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
901
  ] : [],
902
+ ...extras.hasJourneys ? [
903
+ "- `docs/journeys/<journey>.md` \u2014 user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index."
904
+ ] : [],
679
905
  "",
680
906
  "## Doc-first",
681
907
  "",
682
908
  "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
909
  "",
910
+ ...extras.hasJourneys ? [
911
+ "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
912
+ ] : [],
684
913
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
685
914
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
686
915
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -809,6 +1038,23 @@ function getRenderer(engine) {
809
1038
  return RENDERERS[engine];
810
1039
  }
811
1040
 
1041
+ // src/renderers/journeys-index.ts
1042
+ var INTRO = "User intentions and journeys of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/journeys/*.md`: edit the journeys, not this file, then run `npx @vaubaan/harness update .`.";
1043
+ function buildJourneysIndex(journeys) {
1044
+ const lines = ["# Journeys", "", INTRO, ""];
1045
+ const sorted = [...journeys].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
1046
+ for (const journey of sorted) {
1047
+ const status = journey.meta?.status ?? "proposed";
1048
+ const actors = journey.meta?.actors.join(", ") ?? "";
1049
+ lines.push(`- [${journey.title}](./${journey.file}) \u2014 ${status} \xB7 ${actors}`);
1050
+ for (const node of journey.nodes) {
1051
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
1052
+ }
1053
+ }
1054
+ return `${lines.join("\n")}
1055
+ `;
1056
+ }
1057
+
812
1058
  // src/render.ts
813
1059
  var RenderError = class extends Error {
814
1060
  constructor(message) {
@@ -878,12 +1124,16 @@ function render(input) {
878
1124
  availableSkills: Array.from(exposedSkills.values()),
879
1125
  availableCommands: Array.from(exposedCmds.values()),
880
1126
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
881
- hasQualityDoc: input.hasQualityDoc === true
1127
+ hasQualityDoc: input.hasQualityDoc === true,
1128
+ hasJourneys: (input.journeys?.length ?? 0) > 0
882
1129
  });
883
1130
  files.push({ path: "AGENTS.md", content: umbrellaContent });
884
1131
  if (engines.includes("claude-code")) {
885
1132
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
886
1133
  }
1134
+ if (input.journeys && input.journeys.length > 0) {
1135
+ files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
1136
+ }
887
1137
  return { files, warnings };
888
1138
  }
889
1139
 
@@ -915,7 +1165,8 @@ function planInit(args) {
915
1165
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
916
1166
  const projectSkills = loadProjectSkills(args.targetDir);
917
1167
  const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
918
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
1168
+ const journeys = loadJourneys(args.targetDir);
1169
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
919
1170
  return { engines, output };
920
1171
  }
921
1172
 
@@ -962,7 +1213,7 @@ var generatedFresh = {
962
1213
  const full = join8(repoRoot, file.path);
963
1214
  if (!existsSync7(full)) {
964
1215
  issues.push(issue(file.path, `generated file is missing; ${FIX}`));
965
- } else if (readFileSync5(full, "utf8") !== file.content) {
1216
+ } else if (readFileSync6(full, "utf8") !== file.content) {
966
1217
  issues.push(
967
1218
  issue(
968
1219
  file.path,
@@ -993,7 +1244,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
993
1244
  ".codex/",
994
1245
  ".agents/",
995
1246
  ".opencode/",
996
- ".harness-manifest.json"
1247
+ ".harness-manifest.json",
1248
+ "docs/journeys/README.md"
997
1249
  ];
998
1250
  function gitignoreEntries(text) {
999
1251
  const entries = /* @__PURE__ */ new Set();
@@ -1052,9 +1304,211 @@ var gitignoreHarness = {
1052
1304
  }
1053
1305
  };
1054
1306
 
1307
+ // src/linters/journey-anchors.ts
1308
+ var journeyAnchors = {
1309
+ id: "lint:journey-anchors",
1310
+ pillars: ["journeys"],
1311
+ defaultSeverity: "error",
1312
+ suggestedSkills: ["/journey"],
1313
+ run(repoRoot) {
1314
+ const issues = [];
1315
+ for (const journey of readJourneys(repoRoot)) {
1316
+ for (const node of journey.nodes) {
1317
+ if (node.effectiveStatus === "deprecated") continue;
1318
+ for (const anchor of node.anchors) {
1319
+ if (trackedPathExists(repoRoot, anchor)) continue;
1320
+ issues.push({
1321
+ linter: this.id,
1322
+ severity: "error",
1323
+ file: journey.path,
1324
+ line: node.line,
1325
+ message: `"${node.title}": anchor matches no file: ${anchor}`
1326
+ });
1327
+ }
1328
+ }
1329
+ }
1330
+ return issues;
1331
+ }
1332
+ };
1333
+
1334
+ // src/linters/journey-graph.ts
1335
+ var journeyGraph = {
1336
+ id: "lint:journey-graph",
1337
+ pillars: ["journeys"],
1338
+ defaultSeverity: "warning",
1339
+ suggestedSkills: ["/journey"],
1340
+ run(repoRoot) {
1341
+ const journeys = readJourneys(repoRoot);
1342
+ const leaves = journeys.flatMap(
1343
+ (journey) => journey.nodes.filter((node) => node.isLeaf).map((node) => ({ journey, node }))
1344
+ );
1345
+ const created = new Set(leaves.flatMap(({ node }) => node.creates));
1346
+ const issues = [];
1347
+ for (const { journey, node } of leaves) {
1348
+ for (const entity of node.requires) {
1349
+ if (created.has(entity)) continue;
1350
+ issues.push({
1351
+ linter: this.id,
1352
+ severity: "warning",
1353
+ file: journey.path,
1354
+ line: node.line,
1355
+ message: `"${node.title}": entity \`${entity}\` is required here but no leaf creates it`
1356
+ });
1357
+ }
1358
+ }
1359
+ return issues;
1360
+ }
1361
+ };
1362
+
1363
+ // src/linters/journey-util.ts
1364
+ import { posix } from "path";
1365
+ function journeySpecs(meta) {
1366
+ if (!meta) return [];
1367
+ return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
1368
+ }
1369
+ function resolveSpecPath(journeyPath, spec) {
1370
+ const withoutFragment = spec.split("#")[0] ?? "";
1371
+ return posix.normalize(posix.join(posix.dirname(journeyPath), withoutFragment));
1372
+ }
1373
+
1374
+ // src/linters/journey-schema.ts
1375
+ var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
1376
+ var journeySchema = {
1377
+ id: "lint:journey-schema",
1378
+ pillars: ["journeys"],
1379
+ defaultSeverity: "error",
1380
+ suggestedSkills: ["/journey"],
1381
+ run(repoRoot) {
1382
+ const issues = [];
1383
+ for (const journey of readJourneys(repoRoot)) {
1384
+ const report = (message, line) => {
1385
+ issues.push({
1386
+ linter: this.id,
1387
+ severity: "error",
1388
+ file: journey.path,
1389
+ ...line !== void 0 ? { line } : {},
1390
+ message
1391
+ });
1392
+ };
1393
+ for (const error of journey.errors) report(error.message, error.line);
1394
+ for (const spec of journeySpecs(journey.meta)) {
1395
+ if (!fileExists(repoRoot, resolveSpecPath(journey.path, spec))) {
1396
+ report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
1397
+ }
1398
+ }
1399
+ for (const node of journey.nodes) {
1400
+ const at = (message) => report(`"${node.title}": ${message}`, node.line);
1401
+ for (const { key, line } of node.unknownFields) {
1402
+ report(
1403
+ DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
1404
+ line
1405
+ );
1406
+ }
1407
+ if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(journey.path, node.spec))) {
1408
+ report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
1409
+ }
1410
+ if (!node.isLeaf) {
1411
+ for (const field of LEAF_FIELDS) {
1412
+ const line = node.fieldLines[field];
1413
+ if (line !== void 0) {
1414
+ report(
1415
+ `"${node.title}": \`${field}:\` is a leaf field, this node has children`,
1416
+ line
1417
+ );
1418
+ }
1419
+ }
1420
+ continue;
1421
+ }
1422
+ if (Object.keys(node.fieldLines).length === 0) {
1423
+ at("a leaf carries at least one field");
1424
+ continue;
1425
+ }
1426
+ if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
1427
+ at("an `implemented` leaf needs `anchors:`");
1428
+ }
1429
+ if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
1430
+ at("a `proposed` leaf needs `acceptance:` with at least one `- ` item");
1431
+ }
1432
+ }
1433
+ }
1434
+ return issues;
1435
+ }
1436
+ };
1437
+
1438
+ // src/linters/journey-vocabulary.ts
1439
+ var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
1440
+ var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
1441
+ function entitySlug(term) {
1442
+ return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
1443
+ }
1444
+ function vocabularyOf(specText) {
1445
+ const lines = maskFencedCode(specText.split(/\r?\n/));
1446
+ let depth;
1447
+ let terms;
1448
+ for (const line of lines) {
1449
+ const heading = parseHeading(line);
1450
+ if (depth !== void 0) {
1451
+ if (heading && heading.depth <= depth) break;
1452
+ const term = TERM.exec(line)?.[1];
1453
+ if (term) terms?.add(entitySlug(term));
1454
+ continue;
1455
+ }
1456
+ if (heading && VOCABULARY_HEADING.test(line)) {
1457
+ depth = heading.depth;
1458
+ terms = /* @__PURE__ */ new Set();
1459
+ }
1460
+ }
1461
+ return terms;
1462
+ }
1463
+ var journeyVocabulary = {
1464
+ id: "lint:journey-vocabulary",
1465
+ pillars: ["journeys"],
1466
+ defaultSeverity: "error",
1467
+ suggestedSkills: ["/spec"],
1468
+ run(repoRoot) {
1469
+ const issues = [];
1470
+ for (const journey of readJourneys(repoRoot)) {
1471
+ const used = journey.nodes.flatMap(
1472
+ (node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
1473
+ );
1474
+ if (used.length === 0) continue;
1475
+ const specs = journeySpecs(journey.meta).map((spec) => resolveSpecPath(journey.path, spec)).filter((path) => fileExists(repoRoot, path));
1476
+ if (specs.length === 0) continue;
1477
+ const entities = /* @__PURE__ */ new Set();
1478
+ let hasVocabulary = false;
1479
+ for (const spec of specs) {
1480
+ const terms = vocabularyOf(readText(repoRoot, spec));
1481
+ if (!terms) continue;
1482
+ hasVocabulary = true;
1483
+ for (const term of terms) entities.add(term);
1484
+ }
1485
+ if (!hasVocabulary) {
1486
+ issues.push({
1487
+ linter: this.id,
1488
+ severity: "warning",
1489
+ file: journey.path,
1490
+ message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
1491
+ });
1492
+ continue;
1493
+ }
1494
+ for (const { entity, node } of used) {
1495
+ if (entities.has(entity)) continue;
1496
+ issues.push({
1497
+ linter: this.id,
1498
+ severity: "error",
1499
+ file: journey.path,
1500
+ line: node.line,
1501
+ message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
1502
+ });
1503
+ }
1504
+ }
1505
+ return issues;
1506
+ }
1507
+ };
1508
+
1055
1509
  // src/linters/orphan-decisions.ts
1056
- import { basename as basename2 } from "path";
1057
- import fg5 from "fast-glob";
1510
+ import { basename as basename3 } from "path";
1511
+ import fg4 from "fast-glob";
1058
1512
  var orphanDecisions = {
1059
1513
  id: "lint:orphan-decisions",
1060
1514
  pillars: ["decisions"],
@@ -1065,7 +1519,7 @@ var orphanDecisions = {
1065
1519
  const issues = [];
1066
1520
  const adrs = listMarkdown(repoRoot, "docs/decisions");
1067
1521
  if (adrs.length === 0) return issues;
1068
- const otherDocs = fg5.sync("**/*.md", {
1522
+ const otherDocs = fg4.sync("**/*.md", {
1069
1523
  cwd: repoRoot,
1070
1524
  absolute: false,
1071
1525
  ignore: [
@@ -1082,7 +1536,7 @@ var orphanDecisions = {
1082
1536
  });
1083
1537
  const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
1084
1538
  for (const adr of adrs) {
1085
- const filename = basename2(adr);
1539
+ const filename = basename3(adr);
1086
1540
  const stem = filename.replace(/\.md$/, "");
1087
1541
  const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
1088
1542
  if (!referenced) {
@@ -1258,33 +1712,42 @@ var specTechAgnostic = {
1258
1712
  };
1259
1713
 
1260
1714
  // src/linters/tracks-drift.ts
1261
- import fg6 from "fast-glob";
1715
+ import fg5 from "fast-glob";
1262
1716
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
1717
+ var JOURNEYS_DIR2 = "docs/journeys";
1263
1718
  var DEFAULT_DRIFT_THRESHOLD = 10;
1264
1719
  function expandGlob(repoRoot, pattern) {
1265
1720
  if (pattern.includes("*")) {
1266
- return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
1721
+ return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
1267
1722
  }
1268
1723
  return [pattern];
1269
1724
  }
1725
+ function trackedPaths(dir, file, text, data) {
1726
+ if (dir === JOURNEYS_DIR2) {
1727
+ const anchors = parseJourney(file, text).nodes.flatMap((node) => node.anchors);
1728
+ return anchors.length > 0 ? [...new Set(anchors)] : void 0;
1729
+ }
1730
+ return Array.isArray(data.tracks) ? data.tracks : void 0;
1731
+ }
1270
1732
  var tracksDrift = {
1271
1733
  id: "lint:tracks-drift",
1272
- pillars: ["handbook", "tests", "workflow"],
1734
+ pillars: ["handbook", "tests", "workflow", "journeys"],
1273
1735
  defaultSeverity: "warning",
1274
1736
  suggestedSkills: ["/drift", "/handbook"],
1275
1737
  run(repoRoot) {
1276
1738
  const issues = [];
1277
- for (const dir of TRACKED_DIRS2) {
1739
+ for (const dir of [...TRACKED_DIRS2, JOURNEYS_DIR2]) {
1278
1740
  const files = listMarkdown(repoRoot, dir);
1279
1741
  for (const f of files) {
1280
1742
  const text = readText(repoRoot, f);
1281
1743
  const { data } = parseFrontmatter(text);
1282
- if (!Array.isArray(data.tracks)) continue;
1744
+ const tracks = trackedPaths(dir, f, text, data);
1745
+ if (!tracks) continue;
1283
1746
  const docCommit = gitLastCommitForPath(repoRoot, f);
1284
1747
  if (!docCommit) continue;
1285
1748
  const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
1286
1749
  let driftCount = 0;
1287
- for (const tracked of data.tracks) {
1750
+ for (const tracked of tracks) {
1288
1751
  if (typeof tracked !== "string") continue;
1289
1752
  const targets = expandGlob(repoRoot, tracked);
1290
1753
  for (const t of targets.length > 0 ? targets : [tracked]) {
@@ -1321,6 +1784,10 @@ var ALL_LINTERS = [
1321
1784
  orphanDecisions,
1322
1785
  gitignoreHarness,
1323
1786
  qualitySchema,
1787
+ journeySchema,
1788
+ journeyAnchors,
1789
+ journeyVocabulary,
1790
+ journeyGraph,
1324
1791
  generatedFresh
1325
1792
  ];
1326
1793
  function runLinters(repoRoot, opts = {}) {