@vaubaan/harness 2.2.0 → 2.3.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
@@ -364,9 +364,15 @@ var MANAGED_FILES = /* @__PURE__ */ new Set([
364
364
  "AGENTS.md",
365
365
  "CLAUDE.md",
366
366
  ".harness-manifest.json",
367
- // Index of the optional journeys pillar, rendered while a journey exists.
367
+ // Index of the optional intents pillar, rendered while an intent file exists.
368
+ "docs/intents/README.md",
369
+ // Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
368
370
  "docs/journeys/README.md"
369
371
  ]);
372
+ var MOVED_PATHS = /* @__PURE__ */ new Map([
373
+ // 2.3: the journeys pillar became the intents pillar.
374
+ ["docs/journeys/README.md", "docs/intents/README.md"]
375
+ ]);
370
376
  var RELEASED_PATHS = [
371
377
  ".mcp.json",
372
378
  ".codex/config.toml",
@@ -439,7 +445,7 @@ import { join as join4 } from "path";
439
445
  import { z } from "zod";
440
446
 
441
447
  // src/version.ts
442
- var VERSION = "2.2.0";
448
+ var VERSION = "2.3.0";
443
449
 
444
450
  // src/cli/manifest.ts
445
451
  var MANIFEST_FILENAME = ".harness-manifest.json";
@@ -511,12 +517,16 @@ var CmdArgEnumSchema = z2.object({
511
517
  name: z2.string().min(1),
512
518
  type: z2.literal("enum"),
513
519
  values: z2.array(z2.string()).min(1),
514
- default: z2.string().optional()
520
+ default: z2.string().optional(),
521
+ /** False when the command runs without the argument. Defaults to true. */
522
+ required: z2.boolean().optional()
515
523
  }).strict();
516
524
  var CmdArgStringSchema = z2.object({
517
525
  name: z2.string().min(1),
518
526
  type: z2.literal("string"),
519
- default: z2.string().optional()
527
+ default: z2.string().optional(),
528
+ /** False when the command runs without the argument. Defaults to true. */
529
+ required: z2.boolean().optional()
520
530
  }).strict();
521
531
  var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
522
532
  var CmdFrontmatterSchema = z2.object({
@@ -526,10 +536,10 @@ var CmdFrontmatterSchema = z2.object({
526
536
  args: z2.array(CmdArgSchema).optional(),
527
537
  description: z2.string().min(1)
528
538
  }).strict();
529
- var JOURNEY_STATUSES = ["proposed", "implemented", "deprecated"];
530
- var JourneyFrontmatterSchema = z2.object({
539
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
540
+ var IntentFrontmatterSchema = z2.object({
531
541
  title: z2.string().min(1),
532
- status: z2.enum(JOURNEY_STATUSES),
542
+ status: z2.enum(INTENT_STATUSES),
533
543
  actors: z2.array(z2.string().min(1)).min(1),
534
544
  spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
535
545
  last_reviewed: z2.union([z2.date(), z2.string().min(1)])
@@ -537,7 +547,7 @@ var JourneyFrontmatterSchema = z2.object({
537
547
  var Schemas = {
538
548
  Skill: SkillFrontmatterSchema,
539
549
  Cmd: CmdFrontmatterSchema,
540
- Journey: JourneyFrontmatterSchema
550
+ Intent: IntentFrontmatterSchema
541
551
  };
542
552
  var ParseError = class extends Error {
543
553
  constructor(file, issues) {
@@ -621,12 +631,12 @@ function loadOverrides(worktreeDir) {
621
631
  return { add: added, disable };
622
632
  }
623
633
 
624
- // src/parser/journey.ts
634
+ // src/parser/intent.ts
625
635
  import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
626
636
  import { basename as basename2, join as join6 } from "path";
627
637
  import matter3 from "gray-matter";
628
- var JOURNEYS_DIR = "docs/journeys";
629
- var JOURNEYS_INDEX_PATH = `${JOURNEYS_DIR}/README.md`;
638
+ var INTENTS_DIR = "docs/intents";
639
+ var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
630
640
  var NODE_FIELDS = [
631
641
  "status",
632
642
  "spec",
@@ -635,7 +645,7 @@ var NODE_FIELDS = [
635
645
  "requires",
636
646
  "creates"
637
647
  ];
638
- var LEAF_FIELDS = [
648
+ var TERMINAL_FIELDS = [
639
649
  "anchors",
640
650
  "acceptance",
641
651
  "requires",
@@ -686,7 +696,7 @@ function parseFrontmatter2(text, errors) {
686
696
  errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
687
697
  return void 0;
688
698
  }
689
- const result = Schemas.Journey.safeParse(data);
699
+ const result = Schemas.Intent.safeParse(data);
690
700
  if (result.success) return result.data;
691
701
  for (const issue of result.error.issues) {
692
702
  const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
@@ -699,7 +709,7 @@ function newNode(title, level, line) {
699
709
  title,
700
710
  level,
701
711
  line,
702
- isLeaf: true,
712
+ isTerminal: true,
703
713
  fieldLines: {},
704
714
  anchors: [],
705
715
  acceptance: [],
@@ -726,12 +736,12 @@ function parseFields(node, lines, from, to, errors) {
726
736
  const known = key;
727
737
  node.fieldLines[known] = lineNo;
728
738
  if (known === "status") {
729
- if (JOURNEY_STATUSES.includes(value)) {
739
+ if (INTENT_STATUSES.includes(value)) {
730
740
  node.status = value;
731
741
  } else {
732
742
  errors.push({
733
743
  line: lineNo,
734
- message: `invalid status \`${value}\` (expected ${JOURNEY_STATUSES.join(" | ")})`
744
+ message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
735
745
  });
736
746
  }
737
747
  } else if (known === "spec") {
@@ -752,7 +762,7 @@ function parseFields(node, lines, from, to, errors) {
752
762
  return;
753
763
  }
754
764
  }
755
- function parseJourney(relPath, text) {
765
+ function parseIntentFile(relPath, text) {
756
766
  const errors = [];
757
767
  const meta = parseFrontmatter2(text, errors);
758
768
  const lines = maskFencedCode(text.split(/\r?\n/));
@@ -763,7 +773,7 @@ function parseJourney(relPath, text) {
763
773
  if (h) headings.push({ index: i, ...h });
764
774
  }
765
775
  const h1 = headings.find((h) => h.depth === 1);
766
- let story;
776
+ let statement;
767
777
  if (h1) {
768
778
  const paragraph = [];
769
779
  for (let i = h1.index + 1; i < lines.length; i++) {
@@ -775,7 +785,7 @@ function parseJourney(relPath, text) {
775
785
  if (line === MASKED_LINE || parseHeading(line)) break;
776
786
  paragraph.push(line.trim());
777
787
  }
778
- if (paragraph.length) story = paragraph.join(" ");
788
+ if (paragraph.length) statement = paragraph.join(" ");
779
789
  }
780
790
  const nodes = [];
781
791
  const stack = [];
@@ -791,7 +801,7 @@ function parseJourney(relPath, text) {
791
801
  if (parentIndex !== void 0) {
792
802
  node.parent = parentIndex;
793
803
  const parent = nodes[parentIndex];
794
- if (parent) parent.isLeaf = false;
804
+ if (parent) parent.isTerminal = false;
795
805
  }
796
806
  const next = headings[k + 1];
797
807
  parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
@@ -801,32 +811,32 @@ function parseJourney(relPath, text) {
801
811
  nodes.push(node);
802
812
  }
803
813
  const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
804
- return { ...meta ? { meta } : {}, title, ...story ? { story } : {}, nodes, errors };
814
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
805
815
  }
806
- function listJourneyFiles(targetDir) {
807
- const dir = join6(targetDir, JOURNEYS_DIR);
816
+ function listIntentFiles(targetDir) {
817
+ const dir = join6(targetDir, INTENTS_DIR);
808
818
  if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
809
819
  return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
810
820
  }
811
- function readJourneys(targetDir) {
812
- return listJourneyFiles(targetDir).map((file) => {
813
- const path = `${JOURNEYS_DIR}/${file}`;
821
+ function readIntentFiles(targetDir) {
822
+ return listIntentFiles(targetDir).map((file) => {
823
+ const path = `${INTENTS_DIR}/${file}`;
814
824
  const text = readFileSync5(join6(targetDir, path), "utf8");
815
- return { path, file, ...parseJourney(path, text) };
825
+ return { path, file, ...parseIntentFile(path, text) };
816
826
  });
817
827
  }
818
- function loadJourneys(targetDir) {
819
- const journeys = readJourneys(targetDir);
820
- const problems = journeys.flatMap(
828
+ function loadIntentFiles(targetDir) {
829
+ const intentFiles = readIntentFiles(targetDir);
830
+ const problems = intentFiles.flatMap(
821
831
  (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
822
832
  );
823
833
  if (problems.length) {
824
834
  throw new Error(
825
- `invalid journeys (run \`npx @vaubaan/harness lint --pillar journeys\`):
835
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
826
836
  ${problems.join("\n")}`
827
837
  );
828
838
  }
829
- return journeys;
839
+ return intentFiles;
830
840
  }
831
841
 
832
842
  // src/renderers/common.ts
@@ -876,12 +886,13 @@ function frontmatterDataForCmd(cmd) {
876
886
  description: cmd.meta.description
877
887
  };
878
888
  if (cmd.meta.args && cmd.meta.args.length > 0) {
879
- data.args = cmd.meta.args.map((a) => {
880
- if (a.type === "enum") {
881
- 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 };
882
- }
883
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
884
- });
889
+ data.args = cmd.meta.args.map((a) => ({
890
+ name: a.name,
891
+ type: a.type,
892
+ ...a.type === "enum" ? { values: a.values } : {},
893
+ ...a.default !== void 0 ? { default: a.default } : {},
894
+ ...a.required === false ? { required: false } : {}
895
+ }));
885
896
  }
886
897
  return data;
887
898
  }
@@ -914,16 +925,16 @@ function buildUmbrellaBody(extras) {
914
925
  ...extras.hasQualityDoc ? [
915
926
  "- `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."
916
927
  ] : [],
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."
928
+ ...extras.hasIntents ? [
929
+ "- `docs/intents/<intent>.md` \u2014 user intents, one tree per level-1 intent, anchored to the code. `docs/intents/README.md` is the generated index."
919
930
  ] : [],
920
931
  "",
921
932
  "## Doc-first",
922
933
  "",
923
934
  "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.",
924
935
  "",
925
- ...extras.hasJourneys ? [
926
- "- Visible change of behavior \u2192 a `proposed` leaf first (`/story <intent>`), never the code first."
936
+ ...extras.hasIntents ? [
937
+ "- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
927
938
  ] : [],
928
939
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
929
940
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
@@ -1053,16 +1064,16 @@ function getRenderer(engine) {
1053
1064
  return RENDERERS[engine];
1054
1065
  }
1055
1066
 
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) {
1067
+ // src/renderers/intents-index.ts
1068
+ var INTRO = "User intents of this project, anchored to the code. Generated by `@vaubaan/harness` from `docs/intents/*.md`: edit the intents, not this file, then run `npx @vaubaan/harness update .`.";
1069
+ function buildIntentsIndex(intentFiles) {
1070
+ const lines = ["# Intents", "", INTRO, ""];
1071
+ const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
1072
+ for (const intentFile of sorted) {
1073
+ const status = intentFile.meta?.status ?? "proposed";
1074
+ const actors = intentFile.meta?.actors.join(", ") ?? "";
1075
+ lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
1076
+ for (const node of intentFile.nodes) {
1066
1077
  lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
1067
1078
  }
1068
1079
  }
@@ -1140,14 +1151,14 @@ function render(input) {
1140
1151
  availableCommands: Array.from(exposedCmds.values()),
1141
1152
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
1142
1153
  hasQualityDoc: input.hasQualityDoc === true,
1143
- hasJourneys: (input.journeys?.length ?? 0) > 0
1154
+ hasIntents: (input.intentFiles?.length ?? 0) > 0
1144
1155
  });
1145
1156
  files.push({ path: "AGENTS.md", content: umbrellaContent });
1146
1157
  if (engines.includes("claude-code")) {
1147
1158
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
1148
1159
  }
1149
- if (input.journeys && input.journeys.length > 0) {
1150
- files.push({ path: JOURNEYS_INDEX_PATH, content: buildJourneysIndex(input.journeys) });
1160
+ if (input.intentFiles && input.intentFiles.length > 0) {
1161
+ files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
1151
1162
  }
1152
1163
  return { files, warnings };
1153
1164
  }
@@ -1180,8 +1191,8 @@ function planInit(args) {
1180
1191
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
1181
1192
  const projectSkills = loadProjectSkills(args.targetDir);
1182
1193
  const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
1183
- const journeys = loadJourneys(args.targetDir);
1184
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, journeys });
1194
+ const intentFiles = loadIntentFiles(args.targetDir);
1195
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
1185
1196
  return { engines, output };
1186
1197
  }
1187
1198
 
@@ -1260,7 +1271,7 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
1260
1271
  ".agents/",
1261
1272
  ".opencode/",
1262
1273
  ".harness-manifest.json",
1263
- "docs/journeys/README.md"
1274
+ "docs/intents/README.md"
1264
1275
  ];
1265
1276
  function gitignoreEntries(text) {
1266
1277
  const entries = /* @__PURE__ */ new Set();
@@ -1319,23 +1330,23 @@ var gitignoreHarness = {
1319
1330
  }
1320
1331
  };
1321
1332
 
1322
- // src/linters/journey-anchors.ts
1323
- var journeyAnchors = {
1324
- id: "lint:journey-anchors",
1325
- pillars: ["journeys"],
1333
+ // src/linters/intent-anchors.ts
1334
+ var intentAnchors = {
1335
+ id: "lint:intent-anchors",
1336
+ pillars: ["intents"],
1326
1337
  defaultSeverity: "error",
1327
- suggestedSkills: ["/journey"],
1338
+ suggestedSkills: ["/intent"],
1328
1339
  run(repoRoot) {
1329
1340
  const issues = [];
1330
- for (const journey of readJourneys(repoRoot)) {
1331
- for (const node of journey.nodes) {
1341
+ for (const intentFile of readIntentFiles(repoRoot)) {
1342
+ for (const node of intentFile.nodes) {
1332
1343
  if (node.effectiveStatus === "deprecated") continue;
1333
1344
  for (const anchor of node.anchors) {
1334
1345
  if (trackedPathExists(repoRoot, anchor)) continue;
1335
1346
  issues.push({
1336
1347
  linter: this.id,
1337
1348
  severity: "error",
1338
- file: journey.path,
1349
+ file: intentFile.path,
1339
1350
  line: node.line,
1340
1351
  message: `"${node.title}": anchor matches no file: ${anchor}`
1341
1352
  });
@@ -1346,28 +1357,28 @@ var journeyAnchors = {
1346
1357
  }
1347
1358
  };
1348
1359
 
1349
- // src/linters/journey-graph.ts
1350
- var journeyGraph = {
1351
- id: "lint:journey-graph",
1352
- pillars: ["journeys"],
1360
+ // src/linters/intent-graph.ts
1361
+ var intentGraph = {
1362
+ id: "lint:intent-graph",
1363
+ pillars: ["intents"],
1353
1364
  defaultSeverity: "warning",
1354
- suggestedSkills: ["/journey"],
1365
+ suggestedSkills: ["/intent"],
1355
1366
  run(repoRoot) {
1356
- const journeys = readJourneys(repoRoot);
1357
- const leaves = journeys.flatMap(
1358
- (journey) => journey.nodes.filter((node) => node.isLeaf).map((node) => ({ journey, node }))
1367
+ const intentFiles = readIntentFiles(repoRoot);
1368
+ const terminals = intentFiles.flatMap(
1369
+ (intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
1359
1370
  );
1360
- const created = new Set(leaves.flatMap(({ node }) => node.creates));
1371
+ const created = new Set(terminals.flatMap(({ node }) => node.creates));
1361
1372
  const issues = [];
1362
- for (const { journey, node } of leaves) {
1373
+ for (const { intentFile, node } of terminals) {
1363
1374
  for (const entity of node.requires) {
1364
1375
  if (created.has(entity)) continue;
1365
1376
  issues.push({
1366
1377
  linter: this.id,
1367
1378
  severity: "warning",
1368
- file: journey.path,
1379
+ file: intentFile.path,
1369
1380
  line: node.line,
1370
- message: `"${node.title}": entity \`${entity}\` is required here but no leaf creates it`
1381
+ message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
1371
1382
  });
1372
1383
  }
1373
1384
  }
@@ -1375,43 +1386,43 @@ var journeyGraph = {
1375
1386
  }
1376
1387
  };
1377
1388
 
1378
- // src/linters/journey-util.ts
1389
+ // src/linters/intent-util.ts
1379
1390
  import { posix } from "path";
1380
- function journeySpecs(meta) {
1391
+ function intentFileSpecs(meta) {
1381
1392
  if (!meta) return [];
1382
1393
  return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
1383
1394
  }
1384
- function resolveSpecPath(journeyPath, spec) {
1395
+ function resolveSpecPath(filePath, spec) {
1385
1396
  const withoutFragment = spec.split("#")[0] ?? "";
1386
- return posix.normalize(posix.join(posix.dirname(journeyPath), withoutFragment));
1397
+ return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
1387
1398
  }
1388
1399
 
1389
- // src/linters/journey-schema.ts
1400
+ // src/linters/intent-schema.ts
1390
1401
  var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
1391
- var journeySchema = {
1392
- id: "lint:journey-schema",
1393
- pillars: ["journeys"],
1402
+ var intentSchema = {
1403
+ id: "lint:intent-schema",
1404
+ pillars: ["intents"],
1394
1405
  defaultSeverity: "error",
1395
- suggestedSkills: ["/journey"],
1406
+ suggestedSkills: ["/intent"],
1396
1407
  run(repoRoot) {
1397
1408
  const issues = [];
1398
- for (const journey of readJourneys(repoRoot)) {
1409
+ for (const intentFile of readIntentFiles(repoRoot)) {
1399
1410
  const report = (message, line) => {
1400
1411
  issues.push({
1401
1412
  linter: this.id,
1402
1413
  severity: "error",
1403
- file: journey.path,
1414
+ file: intentFile.path,
1404
1415
  ...line !== void 0 ? { line } : {},
1405
1416
  message
1406
1417
  });
1407
1418
  };
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))) {
1419
+ for (const error of intentFile.errors) report(error.message, error.line);
1420
+ for (const spec of intentFileSpecs(intentFile.meta)) {
1421
+ if (!fileExists(repoRoot, resolveSpecPath(intentFile.path, spec))) {
1411
1422
  report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
1412
1423
  }
1413
1424
  }
1414
- for (const node of journey.nodes) {
1425
+ for (const node of intentFile.nodes) {
1415
1426
  const at = (message) => report(`"${node.title}": ${message}`, node.line);
1416
1427
  for (const { key, line } of node.unknownFields) {
1417
1428
  report(
@@ -1419,15 +1430,15 @@ var journeySchema = {
1419
1430
  line
1420
1431
  );
1421
1432
  }
1422
- if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(journey.path, node.spec))) {
1433
+ if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
1423
1434
  report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
1424
1435
  }
1425
- if (!node.isLeaf) {
1426
- for (const field of LEAF_FIELDS) {
1436
+ if (!node.isTerminal) {
1437
+ for (const field of TERMINAL_FIELDS) {
1427
1438
  const line = node.fieldLines[field];
1428
1439
  if (line !== void 0) {
1429
1440
  report(
1430
- `"${node.title}": \`${field}:\` is a leaf field, this node has children`,
1441
+ `"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
1431
1442
  line
1432
1443
  );
1433
1444
  }
@@ -1435,14 +1446,14 @@ var journeySchema = {
1435
1446
  continue;
1436
1447
  }
1437
1448
  if (Object.keys(node.fieldLines).length === 0) {
1438
- at("a leaf carries at least one field");
1449
+ at("a terminal intent carries at least one field");
1439
1450
  continue;
1440
1451
  }
1441
1452
  if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
1442
- at("an `implemented` leaf needs `anchors:`");
1453
+ at("an `implemented` intent needs `anchors:`");
1443
1454
  }
1444
1455
  if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
1445
- at("a `proposed` leaf needs `acceptance:` with at least one `- ` item");
1456
+ at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
1446
1457
  }
1447
1458
  }
1448
1459
  }
@@ -1450,7 +1461,7 @@ var journeySchema = {
1450
1461
  }
1451
1462
  };
1452
1463
 
1453
- // src/linters/journey-vocabulary.ts
1464
+ // src/linters/intent-vocabulary.ts
1454
1465
  var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
1455
1466
  var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
1456
1467
  function entitySlug(term) {
@@ -1475,19 +1486,19 @@ function vocabularyOf(specText) {
1475
1486
  }
1476
1487
  return terms;
1477
1488
  }
1478
- var journeyVocabulary = {
1479
- id: "lint:journey-vocabulary",
1480
- pillars: ["journeys"],
1489
+ var intentVocabulary = {
1490
+ id: "lint:intent-vocabulary",
1491
+ pillars: ["intents"],
1481
1492
  defaultSeverity: "error",
1482
1493
  suggestedSkills: ["/spec"],
1483
1494
  run(repoRoot) {
1484
1495
  const issues = [];
1485
- for (const journey of readJourneys(repoRoot)) {
1486
- const used = journey.nodes.flatMap(
1496
+ for (const intentFile of readIntentFiles(repoRoot)) {
1497
+ const used = intentFile.nodes.flatMap(
1487
1498
  (node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
1488
1499
  );
1489
1500
  if (used.length === 0) continue;
1490
- const specs = journeySpecs(journey.meta).map((spec) => resolveSpecPath(journey.path, spec)).filter((path) => fileExists(repoRoot, path));
1501
+ const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
1491
1502
  if (specs.length === 0) continue;
1492
1503
  const entities = /* @__PURE__ */ new Set();
1493
1504
  let hasVocabulary = false;
@@ -1501,7 +1512,7 @@ var journeyVocabulary = {
1501
1512
  issues.push({
1502
1513
  linter: this.id,
1503
1514
  severity: "warning",
1504
- file: journey.path,
1515
+ file: intentFile.path,
1505
1516
  message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
1506
1517
  });
1507
1518
  continue;
@@ -1511,7 +1522,7 @@ var journeyVocabulary = {
1511
1522
  issues.push({
1512
1523
  linter: this.id,
1513
1524
  severity: "error",
1514
- file: journey.path,
1525
+ file: intentFile.path,
1515
1526
  line: node.line,
1516
1527
  message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
1517
1528
  });
@@ -1729,7 +1740,7 @@ var specTechAgnostic = {
1729
1740
  // src/linters/tracks-drift.ts
1730
1741
  import fg5 from "fast-glob";
1731
1742
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
1732
- var JOURNEYS_DIR2 = "docs/journeys";
1743
+ var INTENTS_DIR2 = "docs/intents";
1733
1744
  var DEFAULT_DRIFT_THRESHOLD = 10;
1734
1745
  function expandGlob(repoRoot, pattern) {
1735
1746
  if (pattern.includes("*")) {
@@ -1738,20 +1749,20 @@ function expandGlob(repoRoot, pattern) {
1738
1749
  return [pattern];
1739
1750
  }
1740
1751
  function trackedPaths(dir, file, text, data) {
1741
- if (dir === JOURNEYS_DIR2) {
1742
- const anchors = parseJourney(file, text).nodes.flatMap((node) => node.anchors);
1752
+ if (dir === INTENTS_DIR2) {
1753
+ const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
1743
1754
  return anchors.length > 0 ? [...new Set(anchors)] : void 0;
1744
1755
  }
1745
1756
  return Array.isArray(data.tracks) ? data.tracks : void 0;
1746
1757
  }
1747
1758
  var tracksDrift = {
1748
1759
  id: "lint:tracks-drift",
1749
- pillars: ["handbook", "tests", "workflow", "journeys"],
1760
+ pillars: ["handbook", "tests", "workflow", "intents"],
1750
1761
  defaultSeverity: "warning",
1751
1762
  suggestedSkills: ["/drift", "/handbook"],
1752
1763
  run(repoRoot) {
1753
1764
  const issues = [];
1754
- for (const dir of [...TRACKED_DIRS2, JOURNEYS_DIR2]) {
1765
+ for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
1755
1766
  const files = listMarkdown(repoRoot, dir);
1756
1767
  for (const f of files) {
1757
1768
  const text = readText(repoRoot, f);
@@ -1799,10 +1810,10 @@ var ALL_LINTERS = [
1799
1810
  orphanDecisions,
1800
1811
  gitignoreHarness,
1801
1812
  qualitySchema,
1802
- journeySchema,
1803
- journeyAnchors,
1804
- journeyVocabulary,
1805
- journeyGraph,
1813
+ intentSchema,
1814
+ intentAnchors,
1815
+ intentVocabulary,
1816
+ intentGraph,
1806
1817
  generatedFresh
1807
1818
  ];
1808
1819
  function runLinters(repoRoot, opts = {}) {
@@ -2145,7 +2156,7 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
2145
2156
  }
2146
2157
 
2147
2158
  // src/cli/update.ts
2148
- import { existsSync as existsSync11, readFileSync as readFileSync11 } from "fs";
2159
+ import { existsSync as existsSync11, readFileSync as readFileSync11, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
2149
2160
  import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
2150
2161
  import { isDeepStrictEqual } from "util";
2151
2162
 
@@ -2221,6 +2232,27 @@ function releaseLegacyPaths(previous, warnings) {
2221
2232
  if (released.length === 0) return previous;
2222
2233
  return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
2223
2234
  }
2235
+ function carryMovedPaths(root, previous, warnings) {
2236
+ let files = previous.files;
2237
+ let fileHashes = previous.fileHashes;
2238
+ for (const [from, to] of MOVED_PATHS) {
2239
+ if (!files.includes(from) || existsSync11(join13(root, from))) continue;
2240
+ files = [...new Set(files.map((path) => path === from ? to : path))];
2241
+ const hash = fileHashes?.[from];
2242
+ if (fileHashes && hash !== void 0) {
2243
+ const { [from]: _moved, ...rest } = fileHashes;
2244
+ fileHashes = { ...rest, [to]: hash };
2245
+ }
2246
+ }
2247
+ const oldDir = join13(root, "docs/journeys");
2248
+ if (existsSync11(oldDir) && statSync4(oldDir).isDirectory() && readdirSync4(oldDir).length > 0) {
2249
+ warnings.push(
2250
+ "docs/journeys/ is now docs/intents/: run `git mv docs/journeys docs/intents`, then `npx @vaubaan/harness update .` again"
2251
+ );
2252
+ }
2253
+ if (files === previous.files) return previous;
2254
+ return { ...previous, files, ...fileHashes ? { fileHashes } : {} };
2255
+ }
2224
2256
  function legacyHookWarnings(root) {
2225
2257
  const warnings = [];
2226
2258
  for (const path of LEGACY_HOOK_FILES) {
@@ -2237,7 +2269,7 @@ function planInstallation(args, settings) {
2237
2269
  const root = resolve7(args.targetDir);
2238
2270
  const { engines } = settings;
2239
2271
  const warnings = [];
2240
- const previous = releaseLegacyPaths(settings.previous, warnings);
2272
+ const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
2241
2273
  const preserved = [
2242
2274
  .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
2243
2275
  ].sort();
@@ -2474,7 +2506,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
2474
2506
  });
2475
2507
  program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
2476
2508
  "--pillar <pillar>",
2477
- "filter by pillar (spec, decisions, handbook, tests, workflow, quality, journeys)"
2509
+ "filter by pillar (spec, decisions, handbook, tests, workflow, quality, intents)"
2478
2510
  ).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) => {
2479
2511
  const repoRoot = resolve9(opts.cwd ?? ".");
2480
2512
  const only = parseList(opts.only);