@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.
package/dist/cli/index.js CHANGED
@@ -17,6 +17,12 @@ function fileExists(repoRoot, relativePath) {
17
17
  function readText(repoRoot, relativePath) {
18
18
  return readFileSync(join(repoRoot, relativePath), "utf8");
19
19
  }
20
+ function trackedPathExists(repoRoot, pattern) {
21
+ if (pattern.includes("*")) {
22
+ return fg.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
23
+ }
24
+ return existsSync(join(repoRoot, pattern));
25
+ }
20
26
  function listMarkdown(repoRoot, dir) {
21
27
  const cwd = join(repoRoot, dir);
22
28
  if (!existsSync(cwd)) return [];
@@ -300,16 +306,7 @@ var docLayout = {
300
306
  };
301
307
 
302
308
  // src/linters/frontmatter-tracks.ts
303
- import { existsSync as existsSync3 } from "fs";
304
- import { join as join3 } from "path";
305
- import fg3 from "fast-glob";
306
309
  var TRACKED_DIRS = ["docs/handbook", "docs/tests", "docs/workflow"];
307
- function trackedPathExists(repoRoot, pattern) {
308
- if (pattern.includes("*")) {
309
- return fg3.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
310
- }
311
- return existsSync3(join3(repoRoot, pattern));
312
- }
313
310
  var frontmatterTracks = {
314
311
  id: "lint:frontmatter-tracks",
315
312
  pillars: ["handbook", "tests", "workflow"],
@@ -357,13 +354,19 @@ var frontmatterTracks = {
357
354
  };
358
355
 
359
356
  // src/linters/generated-fresh.ts
360
- import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
357
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
361
358
  import { join as join8, resolve as resolve4 } from "path";
362
359
 
363
360
  // src/cli/managed-paths.ts
364
361
  import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
365
- import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join4, resolve as resolve2, win32 } from "path";
366
- var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
362
+ import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2, win32 } from "path";
363
+ var MANAGED_FILES = /* @__PURE__ */ new Set([
364
+ "AGENTS.md",
365
+ "CLAUDE.md",
366
+ ".harness-manifest.json",
367
+ // Index of the optional journeys pillar, rendered while a journey exists.
368
+ "docs/journeys/README.md"
369
+ ]);
367
370
  var RELEASED_PATHS = [
368
371
  ".mcp.json",
369
372
  ".codex/config.toml",
@@ -396,7 +399,7 @@ function canonicalTargetRoot(root) {
396
399
  if (!statSync2(canonical).isDirectory()) {
397
400
  throw new Error(`harness target is not a directory: ${root}`);
398
401
  }
399
- return join4(canonical, ...missing);
402
+ return join3(canonical, ...missing);
400
403
  }
401
404
  function assertManagedLocation(path) {
402
405
  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
@@ -411,7 +414,7 @@ function assertNoSymbolicComponents(root, path) {
411
414
  const parts = path.split("/");
412
415
  let current = root;
413
416
  for (const [index, part] of parts.entries()) {
414
- current = join4(current, part);
417
+ current = join3(current, part);
415
418
  const info = lstatSync(current, { throwIfNoEntry: false });
416
419
  if (!info) return;
417
420
  if (info.isSymbolicLink()) {
@@ -431,12 +434,12 @@ function assertManagedPaths(root, files) {
431
434
 
432
435
  // src/cli/manifest.ts
433
436
  import { createHash } from "crypto";
434
- import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
435
- import { join as join5 } from "path";
437
+ import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
438
+ import { join as join4 } from "path";
436
439
  import { z } from "zod";
437
440
 
438
441
  // src/version.ts
439
- var VERSION = "2.1.0";
442
+ var VERSION = "2.2.0";
440
443
 
441
444
  // src/cli/manifest.ts
442
445
  var MANIFEST_FILENAME = ".harness-manifest.json";
@@ -452,7 +455,7 @@ var ManifestSchema = z.object({
452
455
  preservedFiles: z.array(z.string()).optional()
453
456
  });
454
457
  function manifestPath(targetDir) {
455
- return join5(targetDir, MANIFEST_FILENAME);
458
+ return join4(targetDir, MANIFEST_FILENAME);
456
459
  }
457
460
  function hashContent(content) {
458
461
  return createHash("sha256").update(content).digest("hex");
@@ -460,7 +463,7 @@ function hashContent(content) {
460
463
  function readManifest(targetDir) {
461
464
  assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
462
465
  const path = manifestPath(targetDir);
463
- if (!existsSync4(path)) return null;
466
+ if (!existsSync3(path)) return null;
464
467
  const raw = JSON.parse(readFileSync2(path, "utf8"));
465
468
  return ManifestSchema.parse(raw);
466
469
  }
@@ -471,9 +474,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
471
474
  import { fileURLToPath } from "url";
472
475
 
473
476
  // src/loader.ts
474
- import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
475
- import { join as join6 } from "path";
476
- import fg4 from "fast-glob";
477
+ import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
478
+ import { join as join5 } from "path";
479
+ import fg3 from "fast-glob";
477
480
  import { z as z3 } from "zod";
478
481
 
479
482
  // src/parser/common.ts
@@ -523,9 +526,18 @@ var CmdFrontmatterSchema = z2.object({
523
526
  args: z2.array(CmdArgSchema).optional(),
524
527
  description: z2.string().min(1)
525
528
  }).strict();
529
+ var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
530
+ var JourneyFrontmatterSchema = z2.object({
531
+ title: z2.string().min(1),
532
+ status: z2.enum(JOURNEY_STATUSES),
533
+ actors: z2.array(z2.string().min(1)).min(1),
534
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
535
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
536
+ }).strict();
526
537
  var Schemas = {
527
538
  Skill: SkillFrontmatterSchema,
528
- Cmd: CmdFrontmatterSchema
539
+ Cmd: CmdFrontmatterSchema,
540
+ Journey: JourneyFrontmatterSchema
529
541
  };
530
542
  var ParseError = class extends Error {
531
543
  constructor(file, issues) {
@@ -573,31 +585,31 @@ function parseYAML(source) {
573
585
  // src/loader.ts
574
586
  var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
575
587
  function loadHarness(packageDir, opts = {}) {
576
- const skillsDir = opts.skillsDir ?? join6(packageDir, "skills");
577
- const commandsDir = opts.commandsDir ?? join6(packageDir, "commands");
578
- const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
579
- const cmdFiles = fg4.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
588
+ const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
589
+ const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
590
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
591
+ const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
580
592
  return {
581
593
  skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
582
594
  cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
583
595
  };
584
596
  }
585
597
  function loadProjectSkills(targetDir) {
586
- const skillsDir = join6(targetDir, "docs", "skills");
587
- if (!existsSync5(skillsDir)) return [];
588
- const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
598
+ const skillsDir = join5(targetDir, "docs", "skills");
599
+ if (!existsSync4(skillsDir)) return [];
600
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
589
601
  return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
590
602
  }
591
603
  function loadOverrides(worktreeDir) {
592
- const overridesDir = join6(worktreeDir, ".harness-overrides");
593
- if (!existsSync5(overridesDir)) return void 0;
604
+ const overridesDir = join5(worktreeDir, ".harness-overrides");
605
+ if (!existsSync4(overridesDir)) return void 0;
594
606
  const added = loadHarness(overridesDir, {
595
- skillsDir: join6(overridesDir, "skills"),
596
- commandsDir: join6(overridesDir, "commands")
607
+ skillsDir: join5(overridesDir, "skills"),
608
+ commandsDir: join5(overridesDir, "commands")
597
609
  });
598
- const disablePath = join6(overridesDir, "disable.yaml");
610
+ const disablePath = join5(overridesDir, "disable.yaml");
599
611
  let disable = [];
600
- if (existsSync5(disablePath)) {
612
+ if (existsSync4(disablePath)) {
601
613
  try {
602
614
  const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
603
615
  if (parsed.success && parsed.data.disable) {
@@ -609,6 +621,214 @@ function loadOverrides(worktreeDir) {
609
621
  return { add: added, disable };
610
622
  }
611
623
 
624
+ // src/parser/journey.ts
625
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
626
+ import { basename as basename2, join as join6 } from "path";
627
+ import matter3 from "gray-matter";
628
+ var JOURNEYS_DIR = "docs/journeys";
629
+ var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
630
+ var NODE_FIELDS = [
631
+ "status",
632
+ "spec",
633
+ "anchors",
634
+ "acceptance",
635
+ "requires",
636
+ "creates"
637
+ ];
638
+ var LEAF_FIELDS = [
639
+ "anchors",
640
+ "acceptance",
641
+ "requires",
642
+ "creates"
643
+ ];
644
+ var MASKED_LINE = "\0";
645
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
646
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
647
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
648
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
649
+ function maskFencedCode(lines) {
650
+ let fence;
651
+ return lines.map((line) => {
652
+ const m = FENCE_RE.exec(line);
653
+ if (fence !== void 0) {
654
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
655
+ return MASKED_LINE;
656
+ }
657
+ if (m?.[1]) {
658
+ fence = m[1];
659
+ return MASKED_LINE;
660
+ }
661
+ return line;
662
+ });
663
+ }
664
+ function parseHeading(line) {
665
+ const m = HEADING_RE.exec(line);
666
+ if (!m?.[1] || !m[2]) return void 0;
667
+ return { depth: m[1].length, title: m[2] };
668
+ }
669
+ function splitList(value) {
670
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
671
+ }
672
+ function bodyStart(lines) {
673
+ if (lines[0]?.trim() !== "---") return 0;
674
+ for (let i = 1; i < lines.length; i++) {
675
+ const l = lines[i]?.trim();
676
+ if (l === "---" || l === "...") return i + 1;
677
+ }
678
+ return lines.length;
679
+ }
680
+ function parseFrontmatter2(text, errors) {
681
+ let data;
682
+ try {
683
+ data = matter3(text).data;
684
+ } catch (error) {
685
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
686
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
687
+ return void 0;
688
+ }
689
+ const result = Schemas.Journey.safeParse(data);
690
+ if (result.success) return result.data;
691
+ for (const issue of result.error.issues) {
692
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
693
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
694
+ }
695
+ return void 0;
696
+ }
697
+ function newNode(title, level, line) {
698
+ return {
699
+ title,
700
+ level,
701
+ line,
702
+ isLeaf: true,
703
+ fieldLines: {},
704
+ anchors: [],
705
+ acceptance: [],
706
+ requires: [],
707
+ creates: [],
708
+ unknownFields: []
709
+ };
710
+ }
711
+ function parseFields(node, lines, from, to, errors) {
712
+ let lastKey;
713
+ for (let i = from; i < to; i++) {
714
+ const line = lines[i] ?? "";
715
+ if (line.trim() === "") continue;
716
+ const lineNo = i + 1;
717
+ const field = FIELD_RE.exec(line.trimEnd());
718
+ if (field?.[1] !== void 0) {
719
+ const key = field[1];
720
+ const value = (field[2] ?? "").trim();
721
+ lastKey = key;
722
+ if (!NODE_FIELDS.includes(key)) {
723
+ node.unknownFields.push({ key, line: lineNo });
724
+ continue;
725
+ }
726
+ const known = key;
727
+ node.fieldLines[known] = lineNo;
728
+ if (known === "status") {
729
+ if (JOURNEY_STATUSES.includes(value)) {
730
+ node.status = value;
731
+ } else {
732
+ errors.push({
733
+ line: lineNo,
734
+ message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
735
+ });
736
+ }
737
+ } else if (known === "spec") {
738
+ node.spec = value;
739
+ } else if (known === "acceptance") {
740
+ if (value) node.acceptance.push(value);
741
+ } else {
742
+ node[known] = splitList(value);
743
+ }
744
+ continue;
745
+ }
746
+ const item = LIST_ITEM_RE.exec(line);
747
+ if (lastKey === "acceptance" && item) {
748
+ const text = (item[1] ?? "").trim();
749
+ if (text) node.acceptance.push(text);
750
+ continue;
751
+ }
752
+ return;
753
+ }
754
+ }
755
+ function parseJourney(relPath, text) {
756
+ const errors = [];
757
+ const meta = parseFrontmatter2(text, errors);
758
+ const lines = maskFencedCode(text.split(/\r?\n/));
759
+ const start = bodyStart(lines);
760
+ const headings = [];
761
+ for (let i = start; i < lines.length; i++) {
762
+ const h = parseHeading(lines[i] ?? "");
763
+ if (h) headings.push({ index: i, ...h });
764
+ }
765
+ const h1 = headings.find((h) => h.depth === 1);
766
+ let story;
767
+ if (h1) {
768
+ const paragraph = [];
769
+ for (let i = h1.index + 1; i < lines.length; i++) {
770
+ const line = lines[i] ?? "";
771
+ if (line.trim() === "") {
772
+ if (paragraph.length) break;
773
+ continue;
774
+ }
775
+ if (line === MASKED_LINE || parseHeading(line)) break;
776
+ paragraph.push(line.trim());
777
+ }
778
+ if (paragraph.length) story = paragraph.join(" ");
779
+ }
780
+ const nodes = [];
781
+ const stack = [];
782
+ for (const [k, h] of headings.entries()) {
783
+ if (h.depth < 2) continue;
784
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
785
+ while (stack.length) {
786
+ const top = nodes[stack[stack.length - 1]];
787
+ if (top && top.level < node.level) break;
788
+ stack.pop();
789
+ }
790
+ const parentIndex = stack[stack.length - 1];
791
+ if (parentIndex !== void 0) {
792
+ node.parent = parentIndex;
793
+ const parent = nodes[parentIndex];
794
+ if (parent) parent.isLeaf = false;
795
+ }
796
+ const next = headings[k + 1];
797
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
798
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
799
+ node.effectiveStatus = node.status ?? inherited;
800
+ stack.push(nodes.length);
801
+ nodes.push(node);
802
+ }
803
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
804
+ return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
805
+ }
806
+ function listJourneyFiles(targetDir) {
807
+ const dir = join6(targetDir, JOURNEYS_DIR);
808
+ if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
809
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
810
+ }
811
+ function readJourneys(targetDir) {
812
+ return listJourneyFiles(targetDir).map((file) => {
813
+ const path = `${JOURNEYS_DIR}/${file}`;
814
+ const text = readFileSync5(join6(targetDir, path), "utf8");
815
+ return { path, file, ...parseJourney(path, text) };
816
+ });
817
+ }
818
+ function loadJourneys(targetDir) {
819
+ const journeys = readJourneys(targetDir);
820
+ const problems = journeys.flatMap(
821
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
822
+ );
823
+ if (problems.length) {
824
+ throw new Error(
825
+ `invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
826
+ ${problems.join("\n")}`
827
+ );
828
+ }
829
+ return journeys;
830
+ }
831
+
612
832
  // src/renderers/common.ts
613
833
  import { stringify as yamlStringify } from "yaml";
614
834
  function checkSkillCapabilities(skill, engine) {
@@ -666,12 +886,15 @@ function frontmatterDataForCmd(cmd) {
666
886
  return data;
667
887
  }
668
888
  function buildUmbrellaBody(extras) {
669
- const triggerBySkill = new Map(
670
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
671
- );
889
+ const triggersBySkill = /* @__PURE__ */ new Map();
890
+ for (const c of extras.availableCommands) {
891
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
892
+ triggers.push(c.meta.trigger);
893
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
894
+ }
672
895
  const skillLines = extras.availableSkills.map((s) => {
673
- const trigger = triggerBySkill.get(s.meta.id);
674
- const label = trigger ? `\`${s.meta.id}\` (\`${trigger}\`)` : `\`${s.meta.id}\``;
896
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
897
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
675
898
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
676
899
  });
677
900
  const sections = [
@@ -691,11 +914,17 @@ function buildUmbrellaBody(extras) {
691
914
  ...extras.hasQualityDoc ? [
692
915
  "- `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."
693
916
  ] : [],
917
+ ...extras.hasJourneys ? [
918
+ "- `docs/journeys/<journey>.md` \u2014 user intentions and journeys, anchored to the code. `docs/journeys/README.md` is the generated index."
919
+ ] : [],
694
920
  "",
695
921
  "## Doc-first",
696
922
  "",
697
923
  "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.",
698
924
  "",
925
+ ...extras.hasJourneys ? [
926
+ "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
927
+ ] : [],
699
928
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
700
929
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
701
930
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -824,6 +1053,23 @@ function getRenderer(engine) {
824
1053
  return RENDERERS[engine];
825
1054
  }
826
1055
 
1056
+ // src/renderers/journeys-index.ts
1057
+ 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 .`.";
1058
+ function buildJourneysIndex(journeys) {
1059
+ const lines = ["# Journeys", "", INTRO, ""];
1060
+ const sorted = [...journeys].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
1061
+ for (const journey of sorted) {
1062
+ const status = journey.meta?.status ?? "proposed";
1063
+ const actors = journey.meta?.actors.join(", ") ?? "";
1064
+ lines.push(`- [${journey.title}](./${journey.file}) \u2014 ${status} \xB7 ${actors}`);
1065
+ for (const node of journey.nodes) {
1066
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
1067
+ }
1068
+ }
1069
+ return `${lines.join("\n")}
1070
+ `;
1071
+ }
1072
+
827
1073
  // src/render.ts
828
1074
  var RenderError = class extends Error {
829
1075
  constructor(message) {
@@ -893,12 +1139,16 @@ function render(input) {
893
1139
  availableSkills: Array.from(exposedSkills.values()),
894
1140
  availableCommands: Array.from(exposedCmds.values()),
895
1141
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
896
- hasQualityDoc: input.hasQualityDoc === true
1142
+ hasQualityDoc: input.hasQualityDoc === true,
1143
+ hasJourneys: (input.journeys?.length ?? 0) > 0
897
1144
  });
898
1145
  files.push({ path: "AGENTS.md", content: umbrellaContent });
899
1146
  if (engines.includes("claude-code")) {
900
1147
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
901
1148
  }
1149
+ if (input.journeys && input.journeys.length > 0) {
1150
+ files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
1151
+ }
902
1152
  return { files, warnings };
903
1153
  }
904
1154
 
@@ -930,7 +1180,8 @@ function planInit(args) {
930
1180
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
931
1181
  const projectSkills = loadProjectSkills(args.targetDir);
932
1182
  const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
933
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
1183
+ const journeys = loadJourneys(args.targetDir);
1184
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
934
1185
  return { engines, output };
935
1186
  }
936
1187
 
@@ -977,7 +1228,7 @@ var generatedFresh = {
977
1228
  const full = join8(repoRoot, file.path);
978
1229
  if (!existsSync7(full)) {
979
1230
  issues.push(issue(file.path, `generated file is missing; ${FIX}`));
980
- } else if (readFileSync5(full, "utf8") !== file.content) {
1231
+ } else if (readFileSync6(full, "utf8") !== file.content) {
981
1232
  issues.push(
982
1233
  issue(
983
1234
  file.path,
@@ -1008,7 +1259,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
1008
1259
  ".codex/",
1009
1260
  ".agents/",
1010
1261
  ".opencode/",
1011
- ".harness-manifest.json"
1262
+ ".harness-manifest.json",
1263
+ "docs/journeys/README.md"
1012
1264
  ];
1013
1265
  function gitignoreEntries(text) {
1014
1266
  const entries = /* @__PURE__ */ new Set();
@@ -1067,9 +1319,211 @@ var gitignoreHarness = {
1067
1319
  }
1068
1320
  };
1069
1321
 
1322
+ // src/linters/journey-anchors.ts
1323
+ var journeyAnchors = {
1324
+ id: "lint:journey-anchors",
1325
+ pillars: ["journeys"],
1326
+ defaultSeverity: "error",
1327
+ suggestedSkills: ["/journey"],
1328
+ run(repoRoot) {
1329
+ const issues = [];
1330
+ for (const journey of readJourneys(repoRoot)) {
1331
+ for (const node of journey.nodes) {
1332
+ if (node.effectiveStatus === "deprecated") continue;
1333
+ for (const anchor of node.anchors) {
1334
+ if (trackedPathExists(repoRoot, anchor)) continue;
1335
+ issues.push({
1336
+ linter: this.id,
1337
+ severity: "error",
1338
+ file: journey.path,
1339
+ line: node.line,
1340
+ message: `"${node.title}": anchor matches no file: ${anchor}`
1341
+ });
1342
+ }
1343
+ }
1344
+ }
1345
+ return issues;
1346
+ }
1347
+ };
1348
+
1349
+ // src/linters/journey-graph.ts
1350
+ var journeyGraph = {
1351
+ id: "lint:journey-graph",
1352
+ pillars: ["journeys"],
1353
+ defaultSeverity: "warning",
1354
+ suggestedSkills: ["/journey"],
1355
+ run(repoRoot) {
1356
+ const journeys = readJourneys(repoRoot);
1357
+ const leaves = journeys.flatMap(
1358
+ (journey) => journey.nodes.filter((node) => node.isLeaf).map((node) => ({ journey, node }))
1359
+ );
1360
+ const created = new Set(leaves.flatMap(({ node }) => node.creates));
1361
+ const issues = [];
1362
+ for (const { journey, node } of leaves) {
1363
+ for (const entity of node.requires) {
1364
+ if (created.has(entity)) continue;
1365
+ issues.push({
1366
+ linter: this.id,
1367
+ severity: "warning",
1368
+ file: journey.path,
1369
+ line: node.line,
1370
+ message: `"${node.title}": entity \`${entity}\` is required here but no leaf creates it`
1371
+ });
1372
+ }
1373
+ }
1374
+ return issues;
1375
+ }
1376
+ };
1377
+
1378
+ // src/linters/journey-util.ts
1379
+ import { posix } from "path";
1380
+ function journeySpecs(meta) {
1381
+ if (!meta) return [];
1382
+ return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
1383
+ }
1384
+ function resolveSpecPath(journeyPath, spec) {
1385
+ const withoutFragment = spec.split("#")[0] ?? "";
1386
+ return posix.normalize(posix.join(posix.dirname(journeyPath), withoutFragment));
1387
+ }
1388
+
1389
+ // src/linters/journey-schema.ts
1390
+ var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
1391
+ var journeySchema = {
1392
+ id: "lint:journey-schema",
1393
+ pillars: ["journeys"],
1394
+ defaultSeverity: "error",
1395
+ suggestedSkills: ["/journey"],
1396
+ run(repoRoot) {
1397
+ const issues = [];
1398
+ for (const journey of readJourneys(repoRoot)) {
1399
+ const report = (message, line) => {
1400
+ issues.push({
1401
+ linter: this.id,
1402
+ severity: "error",
1403
+ file: journey.path,
1404
+ ...line !== void 0 ? { line } : {},
1405
+ message
1406
+ });
1407
+ };
1408
+ for (const error of journey.errors) report(error.message, error.line);
1409
+ for (const spec of journeySpecs(journey.meta)) {
1410
+ if (!fileExists(repoRoot, resolveSpecPath(journey.path, spec))) {
1411
+ report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
1412
+ }
1413
+ }
1414
+ for (const node of journey.nodes) {
1415
+ const at = (message) => report(`"${node.title}": ${message}`, node.line);
1416
+ for (const { key, line } of node.unknownFields) {
1417
+ report(
1418
+ DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
1419
+ line
1420
+ );
1421
+ }
1422
+ if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(journey.path, node.spec))) {
1423
+ report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
1424
+ }
1425
+ if (!node.isLeaf) {
1426
+ for (const field of LEAF_FIELDS) {
1427
+ const line = node.fieldLines[field];
1428
+ if (line !== void 0) {
1429
+ report(
1430
+ `"${node.title}": \`${field}:\` is a leaf field, this node has children`,
1431
+ line
1432
+ );
1433
+ }
1434
+ }
1435
+ continue;
1436
+ }
1437
+ if (Object.keys(node.fieldLines).length === 0) {
1438
+ at("a leaf carries at least one field");
1439
+ continue;
1440
+ }
1441
+ if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
1442
+ at("an `implemented` leaf needs `anchors:`");
1443
+ }
1444
+ if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
1445
+ at("a `proposed` leaf needs `acceptance:` with at least one `- ` item");
1446
+ }
1447
+ }
1448
+ }
1449
+ return issues;
1450
+ }
1451
+ };
1452
+
1453
+ // src/linters/journey-vocabulary.ts
1454
+ var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
1455
+ var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
1456
+ function entitySlug(term) {
1457
+ return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
1458
+ }
1459
+ function vocabularyOf(specText) {
1460
+ const lines = maskFencedCode(specText.split(/\r?\n/));
1461
+ let depth;
1462
+ let terms;
1463
+ for (const line of lines) {
1464
+ const heading = parseHeading(line);
1465
+ if (depth !== void 0) {
1466
+ if (heading && heading.depth <= depth) break;
1467
+ const term = TERM.exec(line)?.[1];
1468
+ if (term) terms?.add(entitySlug(term));
1469
+ continue;
1470
+ }
1471
+ if (heading && VOCABULARY_HEADING.test(line)) {
1472
+ depth = heading.depth;
1473
+ terms = /* @__PURE__ */ new Set();
1474
+ }
1475
+ }
1476
+ return terms;
1477
+ }
1478
+ var journeyVocabulary = {
1479
+ id: "lint:journey-vocabulary",
1480
+ pillars: ["journeys"],
1481
+ defaultSeverity: "error",
1482
+ suggestedSkills: ["/spec"],
1483
+ run(repoRoot) {
1484
+ const issues = [];
1485
+ for (const journey of readJourneys(repoRoot)) {
1486
+ const used = journey.nodes.flatMap(
1487
+ (node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
1488
+ );
1489
+ if (used.length === 0) continue;
1490
+ const specs = journeySpecs(journey.meta).map((spec) => resolveSpecPath(journey.path, spec)).filter((path) => fileExists(repoRoot, path));
1491
+ if (specs.length === 0) continue;
1492
+ const entities = /* @__PURE__ */ new Set();
1493
+ let hasVocabulary = false;
1494
+ for (const spec of specs) {
1495
+ const terms = vocabularyOf(readText(repoRoot, spec));
1496
+ if (!terms) continue;
1497
+ hasVocabulary = true;
1498
+ for (const term of terms) entities.add(term);
1499
+ }
1500
+ if (!hasVocabulary) {
1501
+ issues.push({
1502
+ linter: this.id,
1503
+ severity: "warning",
1504
+ file: journey.path,
1505
+ message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
1506
+ });
1507
+ continue;
1508
+ }
1509
+ for (const { entity, node } of used) {
1510
+ if (entities.has(entity)) continue;
1511
+ issues.push({
1512
+ linter: this.id,
1513
+ severity: "error",
1514
+ file: journey.path,
1515
+ line: node.line,
1516
+ message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
1517
+ });
1518
+ }
1519
+ }
1520
+ return issues;
1521
+ }
1522
+ };
1523
+
1070
1524
  // src/linters/orphan-decisions.ts
1071
- import { basename as basename2 } from "path";
1072
- import fg5 from "fast-glob";
1525
+ import { basename as basename3 } from "path";
1526
+ import fg4 from "fast-glob";
1073
1527
  var orphanDecisions = {
1074
1528
  id: "lint:orphan-decisions",
1075
1529
  pillars: ["decisions"],
@@ -1080,7 +1534,7 @@ var orphanDecisions = {
1080
1534
  const issues = [];
1081
1535
  const adrs = listMarkdown(repoRoot, "docs/decisions");
1082
1536
  if (adrs.length === 0) return issues;
1083
- const otherDocs = fg5.sync("**/*.md", {
1537
+ const otherDocs = fg4.sync("**/*.md", {
1084
1538
  cwd: repoRoot,
1085
1539
  absolute: false,
1086
1540
  ignore: [
@@ -1097,7 +1551,7 @@ var orphanDecisions = {
1097
1551
  });
1098
1552
  const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
1099
1553
  for (const adr of adrs) {
1100
- const filename = basename2(adr);
1554
+ const filename = basename3(adr);
1101
1555
  const stem = filename.replace(/\.md$/, "");
1102
1556
  const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
1103
1557
  if (!referenced) {
@@ -1273,33 +1727,42 @@ var specTechAgnostic = {
1273
1727
  };
1274
1728
 
1275
1729
  // src/linters/tracks-drift.ts
1276
- import fg6 from "fast-glob";
1730
+ import fg5 from "fast-glob";
1277
1731
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
1732
+ var JOURNEYS_DIR2 = "docs/journeys";
1278
1733
  var DEFAULT_DRIFT_THRESHOLD = 10;
1279
1734
  function expandGlob(repoRoot, pattern) {
1280
1735
  if (pattern.includes("*")) {
1281
- return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
1736
+ return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
1282
1737
  }
1283
1738
  return [pattern];
1284
1739
  }
1740
+ function trackedPaths(dir, file, text, data) {
1741
+ if (dir === JOURNEYS_DIR2) {
1742
+ const anchors = parseJourney(file, text).nodes.flatMap((node) => node.anchors);
1743
+ return anchors.length > 0 ? [...new Set(anchors)] : void 0;
1744
+ }
1745
+ return Array.isArray(data.tracks) ? data.tracks : void 0;
1746
+ }
1285
1747
  var tracksDrift = {
1286
1748
  id: "lint:tracks-drift",
1287
- pillars: ["handbook", "tests", "workflow"],
1749
+ pillars: ["handbook", "tests", "workflow", "journeys"],
1288
1750
  defaultSeverity: "warning",
1289
1751
  suggestedSkills: ["/drift", "/handbook"],
1290
1752
  run(repoRoot) {
1291
1753
  const issues = [];
1292
- for (const dir of TRACKED_DIRS2) {
1754
+ for (const dir of [...TRACKED_DIRS2, JOURNEYS_DIR2]) {
1293
1755
  const files = listMarkdown(repoRoot, dir);
1294
1756
  for (const f of files) {
1295
1757
  const text = readText(repoRoot, f);
1296
1758
  const { data } = parseFrontmatter(text);
1297
- if (!Array.isArray(data.tracks)) continue;
1759
+ const tracks = trackedPaths(dir, f, text, data);
1760
+ if (!tracks) continue;
1298
1761
  const docCommit = gitLastCommitForPath(repoRoot, f);
1299
1762
  if (!docCommit) continue;
1300
1763
  const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
1301
1764
  let driftCount = 0;
1302
- for (const tracked of data.tracks) {
1765
+ for (const tracked of tracks) {
1303
1766
  if (typeof tracked !== "string") continue;
1304
1767
  const targets = expandGlob(repoRoot, tracked);
1305
1768
  for (const t of targets.length > 0 ? targets : [tracked]) {
@@ -1336,6 +1799,10 @@ var ALL_LINTERS = [
1336
1799
  orphanDecisions,
1337
1800
  gitignoreHarness,
1338
1801
  qualitySchema,
1802
+ journeySchema,
1803
+ journeyAnchors,
1804
+ journeyVocabulary,
1805
+ journeyGraph,
1339
1806
  generatedFresh
1340
1807
  ];
1341
1808
  function runLinters(repoRoot, opts = {}) {
@@ -1391,7 +1858,7 @@ function formatReportText(report) {
1391
1858
  }
1392
1859
 
1393
1860
  // src/cli/check.ts
1394
- import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
1861
+ import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
1395
1862
  import { join as join9 } from "path";
1396
1863
  var REQUIRED_DIRS2 = [
1397
1864
  "docs/spec",
@@ -1414,7 +1881,7 @@ function checkCommand(repoRoot) {
1414
1881
  if (!existsSync8(gitignorePath)) {
1415
1882
  issues.push(".gitignore missing at repo root");
1416
1883
  } else {
1417
- const text = readFileSync6(gitignorePath, "utf8");
1884
+ const text = readFileSync7(gitignorePath, "utf8");
1418
1885
  for (const entry of missingGitignoreEntries(text)) {
1419
1886
  issues.push(`.gitignore missing entry: ${entry}`);
1420
1887
  }
@@ -1430,7 +1897,7 @@ import { existsSync as existsSync12, mkdirSync as mkdirSync2, rmSync, writeFileS
1430
1897
  import { dirname as dirname7, join as join14, resolve as resolve8 } from "path";
1431
1898
 
1432
1899
  // src/cli/uninstall.ts
1433
- import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync, rmdirSync, unlinkSync } from "fs";
1900
+ import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
1434
1901
  import { dirname as dirname4, join as join10, relative as relative2, resolve as resolve5 } from "path";
1435
1902
  function uninstallCommand(args) {
1436
1903
  const root = resolve5(args.targetDir);
@@ -1447,7 +1914,7 @@ function uninstallCommand(args) {
1447
1914
  const modified = files.filter((file) => {
1448
1915
  const hash = manifest.fileHashes?.[file];
1449
1916
  const full = join10(root, file);
1450
- return hash !== void 0 && existsSync9(full) && hashContent(readFileSync7(full)) !== hash;
1917
+ return hash !== void 0 && existsSync9(full) && hashContent(readFileSync8(full)) !== hash;
1451
1918
  });
1452
1919
  const ownedFiles = files.filter((file) => !modified.includes(file));
1453
1920
  const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
@@ -1489,7 +1956,7 @@ function pruneEmptyDirs(root, leaves) {
1489
1956
  const sorted = [...candidates].sort((a, b) => b.length - a.length);
1490
1957
  for (const dir of sorted) {
1491
1958
  if (!existsSync9(dir)) continue;
1492
- if (readdirSync(dir).length > 0) continue;
1959
+ if (readdirSync2(dir).length > 0) continue;
1493
1960
  rmdirSync(dir);
1494
1961
  pruned.push(relative2(root, dir));
1495
1962
  }
@@ -1505,22 +1972,22 @@ import {
1505
1972
  lstatSync as lstatSync2,
1506
1973
  mkdirSync,
1507
1974
  openSync,
1508
- readFileSync as readFileSync8,
1509
- readdirSync as readdirSync2,
1975
+ readFileSync as readFileSync9,
1976
+ readdirSync as readdirSync3,
1510
1977
  realpathSync as realpathSync2,
1511
1978
  rmdirSync as rmdirSync2,
1512
1979
  unlinkSync as unlinkSync2,
1513
1980
  writeFileSync as writeFileSync2
1514
1981
  } from "fs";
1515
1982
  import { homedir } from "os";
1516
- import { basename as basename3, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
1983
+ import { basename as basename4, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
1517
1984
  var MANIFEST_PATH = ".harness-manifest.json";
1518
1985
  var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
1519
1986
  function canonicalRoot(root) {
1520
1987
  let ancestor = resolve6(root);
1521
1988
  const missing = [];
1522
1989
  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
1523
- missing.unshift(basename3(ancestor));
1990
+ missing.unshift(basename4(ancestor));
1524
1991
  ancestor = dirname5(ancestor);
1525
1992
  }
1526
1993
  return join11(realpathSync2(ancestor), ...missing);
@@ -1580,7 +2047,7 @@ function saveSnapshot(root, paths, backup) {
1580
2047
  entries.push({ path, exists: false });
1581
2048
  continue;
1582
2049
  }
1583
- const content = readFileSync8(full);
2050
+ const content = readFileSync9(full);
1584
2051
  writeBackupFile(join11(backup, "files", path), content);
1585
2052
  entries.push({
1586
2053
  path,
@@ -1611,8 +2078,8 @@ function rollback(root, backup, entries, touched, createdDirectories) {
1611
2078
  if (current) unlinkSync2(full);
1612
2079
  continue;
1613
2080
  }
1614
- const original = readFileSync8(join11(backup, "files", path));
1615
- if (!current || !readFileSync8(full).equals(original)) {
2081
+ const original = readFileSync9(join11(backup, "files", path));
2082
+ if (!current || !readFileSync9(full).equals(original)) {
1616
2083
  if (current) unlinkSync2(full);
1617
2084
  writeFileSync2(full, original, { mode: 384 });
1618
2085
  }
@@ -1623,7 +2090,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
1623
2090
  }
1624
2091
  for (const directory of [...createdDirectories].reverse()) {
1625
2092
  try {
1626
- if (readdirSync2(directory).length === 0) rmdirSync2(directory);
2093
+ if (readdirSync3(directory).length === 0) rmdirSync2(directory);
1627
2094
  } catch (error) {
1628
2095
  errors.push(`${directory}: ${errorMessage(error)}`);
1629
2096
  }
@@ -1678,12 +2145,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
1678
2145
  }
1679
2146
 
1680
2147
  // src/cli/update.ts
1681
- import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
2148
+ import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
1682
2149
  import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
1683
2150
  import { isDeepStrictEqual } from "util";
1684
2151
 
1685
2152
  // src/cli/update-manifest.ts
1686
- import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
2153
+ import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
1687
2154
  import { join as join12 } from "path";
1688
2155
  import { z as z4 } from "zod";
1689
2156
  var EngineSchema = z4.enum(ENGINES);
@@ -1699,7 +2166,7 @@ function readUpdateInstallation(root) {
1699
2166
  if (!existsSync10(join12(root, MANIFEST_FILENAME))) {
1700
2167
  throw new Error("no harness manifest found; use init for a new installation");
1701
2168
  }
1702
- const raw = JSON.parse(readFileSync9(join12(root, MANIFEST_FILENAME), "utf8"));
2169
+ const raw = JSON.parse(readFileSync10(join12(root, MANIFEST_FILENAME), "utf8"));
1703
2170
  const sourceVersion = String(raw?.version);
1704
2171
  let manifest;
1705
2172
  if (["1", "2", "3"].includes(sourceVersion)) {
@@ -1724,7 +2191,7 @@ function readUpdateInstallation(root) {
1724
2191
  var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
1725
2192
  var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
1726
2193
  function currentContent(root, path) {
1727
- return existsSync11(join13(root, path)) ? readFileSync10(join13(root, path), "utf8") : void 0;
2194
+ return existsSync11(join13(root, path)) ? readFileSync11(join13(root, path), "utf8") : void 0;
1728
2195
  }
1729
2196
  function checkArtifactConflicts(root, previous, writes, removals) {
1730
2197
  const desired = new Map(writes.map((file) => [file.path, file.content]));
@@ -1786,7 +2253,7 @@ function planInstallation(args, settings) {
1786
2253
  const disablePath = join13(overridesDir, ".harness-overrides", "disable.yaml");
1787
2254
  if (existsSync11(disablePath)) {
1788
2255
  try {
1789
- DisableYamlSchema.parse(parseYAML(readFileSync10(disablePath, "utf8")));
2256
+ DisableYamlSchema.parse(parseYAML(readFileSync11(disablePath, "utf8")));
1790
2257
  } catch {
1791
2258
  throw new Error(`invalid override selection: ${disablePath}`);
1792
2259
  }
@@ -2007,7 +2474,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
2007
2474
  });
2008
2475
  program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
2009
2476
  "--pillar <pillar>",
2010
- "filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
2477
+ "filter by pillar (spec, decisions, handbook, tests, workflow, quality, journeys)"
2011
2478
  ).option("--only <ids>", "comma-separated linter ids to run (e.g. lint:cross-links)").option("--format <fmt>", "text | json", "text").option("--cwd <dir>", "repo root", ".").action((opts) => {
2012
2479
  const repoRoot = resolve9(opts.cwd ?? ".");
2013
2480
  const only = parseList(opts.only);