@vaubaan/harness 2.1.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
@@ -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,25 @@ 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 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).
370
+ "docs/journeys/README.md"
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
+ ]);
367
376
  var RELEASED_PATHS = [
368
377
  ".mcp.json",
369
378
  ".codex/config.toml",
@@ -396,7 +405,7 @@ function canonicalTargetRoot(root) {
396
405
  if (!statSync2(canonical).isDirectory()) {
397
406
  throw new Error(`harness target is not a directory: ${root}`);
398
407
  }
399
- return join4(canonical, ...missing);
408
+ return join3(canonical, ...missing);
400
409
  }
401
410
  function assertManagedLocation(path) {
402
411
  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
@@ -411,7 +420,7 @@ function assertNoSymbolicComponents(root, path) {
411
420
  const parts = path.split("/");
412
421
  let current = root;
413
422
  for (const [index, part] of parts.entries()) {
414
- current = join4(current, part);
423
+ current = join3(current, part);
415
424
  const info = lstatSync(current, { throwIfNoEntry: false });
416
425
  if (!info) return;
417
426
  if (info.isSymbolicLink()) {
@@ -431,12 +440,12 @@ function assertManagedPaths(root, files) {
431
440
 
432
441
  // src/cli/manifest.ts
433
442
  import { createHash } from "crypto";
434
- import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
435
- import { join as join5 } from "path";
443
+ import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
444
+ import { join as join4 } from "path";
436
445
  import { z } from "zod";
437
446
 
438
447
  // src/version.ts
439
- var VERSION = "2.1.0";
448
+ var VERSION = "2.3.0";
440
449
 
441
450
  // src/cli/manifest.ts
442
451
  var MANIFEST_FILENAME = ".harness-manifest.json";
@@ -452,7 +461,7 @@ var ManifestSchema = z.object({
452
461
  preservedFiles: z.array(z.string()).optional()
453
462
  });
454
463
  function manifestPath(targetDir) {
455
- return join5(targetDir, MANIFEST_FILENAME);
464
+ return join4(targetDir, MANIFEST_FILENAME);
456
465
  }
457
466
  function hashContent(content) {
458
467
  return createHash("sha256").update(content).digest("hex");
@@ -460,7 +469,7 @@ function hashContent(content) {
460
469
  function readManifest(targetDir) {
461
470
  assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
462
471
  const path = manifestPath(targetDir);
463
- if (!existsSync4(path)) return null;
472
+ if (!existsSync3(path)) return null;
464
473
  const raw = JSON.parse(readFileSync2(path, "utf8"));
465
474
  return ManifestSchema.parse(raw);
466
475
  }
@@ -471,9 +480,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
471
480
  import { fileURLToPath } from "url";
472
481
 
473
482
  // 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";
483
+ import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
484
+ import { join as join5 } from "path";
485
+ import fg3 from "fast-glob";
477
486
  import { z as z3 } from "zod";
478
487
 
479
488
  // src/parser/common.ts
@@ -508,12 +517,16 @@ var CmdArgEnumSchema = z2.object({
508
517
  name: z2.string().min(1),
509
518
  type: z2.literal("enum"),
510
519
  values: z2.array(z2.string()).min(1),
511
- 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()
512
523
  }).strict();
513
524
  var CmdArgStringSchema = z2.object({
514
525
  name: z2.string().min(1),
515
526
  type: z2.literal("string"),
516
- 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()
517
530
  }).strict();
518
531
  var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
519
532
  var CmdFrontmatterSchema = z2.object({
@@ -523,9 +536,18 @@ var CmdFrontmatterSchema = z2.object({
523
536
  args: z2.array(CmdArgSchema).optional(),
524
537
  description: z2.string().min(1)
525
538
  }).strict();
539
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
540
+ var IntentFrontmatterSchema = z2.object({
541
+ title: z2.string().min(1),
542
+ status: z2.enum(INTENT_STATUSES),
543
+ actors: z2.array(z2.string().min(1)).min(1),
544
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
545
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
546
+ }).strict();
526
547
  var Schemas = {
527
548
  Skill: SkillFrontmatterSchema,
528
- Cmd: CmdFrontmatterSchema
549
+ Cmd: CmdFrontmatterSchema,
550
+ Intent: IntentFrontmatterSchema
529
551
  };
530
552
  var ParseError = class extends Error {
531
553
  constructor(file, issues) {
@@ -573,31 +595,31 @@ function parseYAML(source) {
573
595
  // src/loader.ts
574
596
  var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
575
597
  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 });
598
+ const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
599
+ const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
600
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
601
+ const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
580
602
  return {
581
603
  skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
582
604
  cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
583
605
  };
584
606
  }
585
607
  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 });
608
+ const skillsDir = join5(targetDir, "docs", "skills");
609
+ if (!existsSync4(skillsDir)) return [];
610
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
589
611
  return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
590
612
  }
591
613
  function loadOverrides(worktreeDir) {
592
- const overridesDir = join6(worktreeDir, ".harness-overrides");
593
- if (!existsSync5(overridesDir)) return void 0;
614
+ const overridesDir = join5(worktreeDir, ".harness-overrides");
615
+ if (!existsSync4(overridesDir)) return void 0;
594
616
  const added = loadHarness(overridesDir, {
595
- skillsDir: join6(overridesDir, "skills"),
596
- commandsDir: join6(overridesDir, "commands")
617
+ skillsDir: join5(overridesDir, "skills"),
618
+ commandsDir: join5(overridesDir, "commands")
597
619
  });
598
- const disablePath = join6(overridesDir, "disable.yaml");
620
+ const disablePath = join5(overridesDir, "disable.yaml");
599
621
  let disable = [];
600
- if (existsSync5(disablePath)) {
622
+ if (existsSync4(disablePath)) {
601
623
  try {
602
624
  const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
603
625
  if (parsed.success && parsed.data.disable) {
@@ -609,6 +631,214 @@ function loadOverrides(worktreeDir) {
609
631
  return { add: added, disable };
610
632
  }
611
633
 
634
+ // src/parser/intent.ts
635
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
636
+ import { basename as basename2, join as join6 } from "path";
637
+ import matter3 from "gray-matter";
638
+ var INTENTS_DIR = "docs/intents";
639
+ var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
640
+ var NODE_FIELDS = [
641
+ "status",
642
+ "spec",
643
+ "anchors",
644
+ "acceptance",
645
+ "requires",
646
+ "creates"
647
+ ];
648
+ var TERMINAL_FIELDS = [
649
+ "anchors",
650
+ "acceptance",
651
+ "requires",
652
+ "creates"
653
+ ];
654
+ var MASKED_LINE = "\0";
655
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
656
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
657
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
658
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
659
+ function maskFencedCode(lines) {
660
+ let fence;
661
+ return lines.map((line) => {
662
+ const m = FENCE_RE.exec(line);
663
+ if (fence !== void 0) {
664
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
665
+ return MASKED_LINE;
666
+ }
667
+ if (m?.[1]) {
668
+ fence = m[1];
669
+ return MASKED_LINE;
670
+ }
671
+ return line;
672
+ });
673
+ }
674
+ function parseHeading(line) {
675
+ const m = HEADING_RE.exec(line);
676
+ if (!m?.[1] || !m[2]) return void 0;
677
+ return { depth: m[1].length, title: m[2] };
678
+ }
679
+ function splitList(value) {
680
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
681
+ }
682
+ function bodyStart(lines) {
683
+ if (lines[0]?.trim() !== "---") return 0;
684
+ for (let i = 1; i < lines.length; i++) {
685
+ const l = lines[i]?.trim();
686
+ if (l === "---" || l === "...") return i + 1;
687
+ }
688
+ return lines.length;
689
+ }
690
+ function parseFrontmatter2(text, errors) {
691
+ let data;
692
+ try {
693
+ data = matter3(text).data;
694
+ } catch (error) {
695
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
696
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
697
+ return void 0;
698
+ }
699
+ const result = Schemas.Intent.safeParse(data);
700
+ if (result.success) return result.data;
701
+ for (const issue of result.error.issues) {
702
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
703
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
704
+ }
705
+ return void 0;
706
+ }
707
+ function newNode(title, level, line) {
708
+ return {
709
+ title,
710
+ level,
711
+ line,
712
+ isTerminal: true,
713
+ fieldLines: {},
714
+ anchors: [],
715
+ acceptance: [],
716
+ requires: [],
717
+ creates: [],
718
+ unknownFields: []
719
+ };
720
+ }
721
+ function parseFields(node, lines, from, to, errors) {
722
+ let lastKey;
723
+ for (let i = from; i < to; i++) {
724
+ const line = lines[i] ?? "";
725
+ if (line.trim() === "") continue;
726
+ const lineNo = i + 1;
727
+ const field = FIELD_RE.exec(line.trimEnd());
728
+ if (field?.[1] !== void 0) {
729
+ const key = field[1];
730
+ const value = (field[2] ?? "").trim();
731
+ lastKey = key;
732
+ if (!NODE_FIELDS.includes(key)) {
733
+ node.unknownFields.push({ key, line: lineNo });
734
+ continue;
735
+ }
736
+ const known = key;
737
+ node.fieldLines[known] = lineNo;
738
+ if (known === "status") {
739
+ if (INTENT_STATUSES.includes(value)) {
740
+ node.status = value;
741
+ } else {
742
+ errors.push({
743
+ line: lineNo,
744
+ message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
745
+ });
746
+ }
747
+ } else if (known === "spec") {
748
+ node.spec = value;
749
+ } else if (known === "acceptance") {
750
+ if (value) node.acceptance.push(value);
751
+ } else {
752
+ node[known] = splitList(value);
753
+ }
754
+ continue;
755
+ }
756
+ const item = LIST_ITEM_RE.exec(line);
757
+ if (lastKey === "acceptance" && item) {
758
+ const text = (item[1] ?? "").trim();
759
+ if (text) node.acceptance.push(text);
760
+ continue;
761
+ }
762
+ return;
763
+ }
764
+ }
765
+ function parseIntentFile(relPath, text) {
766
+ const errors = [];
767
+ const meta = parseFrontmatter2(text, errors);
768
+ const lines = maskFencedCode(text.split(/\r?\n/));
769
+ const start = bodyStart(lines);
770
+ const headings = [];
771
+ for (let i = start; i < lines.length; i++) {
772
+ const h = parseHeading(lines[i] ?? "");
773
+ if (h) headings.push({ index: i, ...h });
774
+ }
775
+ const h1 = headings.find((h) => h.depth === 1);
776
+ let statement;
777
+ if (h1) {
778
+ const paragraph = [];
779
+ for (let i = h1.index + 1; i < lines.length; i++) {
780
+ const line = lines[i] ?? "";
781
+ if (line.trim() === "") {
782
+ if (paragraph.length) break;
783
+ continue;
784
+ }
785
+ if (line === MASKED_LINE || parseHeading(line)) break;
786
+ paragraph.push(line.trim());
787
+ }
788
+ if (paragraph.length) statement = paragraph.join(" ");
789
+ }
790
+ const nodes = [];
791
+ const stack = [];
792
+ for (const [k, h] of headings.entries()) {
793
+ if (h.depth < 2) continue;
794
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
795
+ while (stack.length) {
796
+ const top = nodes[stack[stack.length - 1]];
797
+ if (top && top.level < node.level) break;
798
+ stack.pop();
799
+ }
800
+ const parentIndex = stack[stack.length - 1];
801
+ if (parentIndex !== void 0) {
802
+ node.parent = parentIndex;
803
+ const parent = nodes[parentIndex];
804
+ if (parent) parent.isTerminal = false;
805
+ }
806
+ const next = headings[k + 1];
807
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
808
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
809
+ node.effectiveStatus = node.status ?? inherited;
810
+ stack.push(nodes.length);
811
+ nodes.push(node);
812
+ }
813
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
814
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
815
+ }
816
+ function listIntentFiles(targetDir) {
817
+ const dir = join6(targetDir, INTENTS_DIR);
818
+ if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
819
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
820
+ }
821
+ function readIntentFiles(targetDir) {
822
+ return listIntentFiles(targetDir).map((file) => {
823
+ const path = `${INTENTS_DIR}/${file}`;
824
+ const text = readFileSync5(join6(targetDir, path), "utf8");
825
+ return { path, file, ...parseIntentFile(path, text) };
826
+ });
827
+ }
828
+ function loadIntentFiles(targetDir) {
829
+ const intentFiles = readIntentFiles(targetDir);
830
+ const problems = intentFiles.flatMap(
831
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
832
+ );
833
+ if (problems.length) {
834
+ throw new Error(
835
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
836
+ ${problems.join("\n")}`
837
+ );
838
+ }
839
+ return intentFiles;
840
+ }
841
+
612
842
  // src/renderers/common.ts
613
843
  import { stringify as yamlStringify } from "yaml";
614
844
  function checkSkillCapabilities(skill, engine) {
@@ -656,22 +886,26 @@ function frontmatterDataForCmd(cmd) {
656
886
  description: cmd.meta.description
657
887
  };
658
888
  if (cmd.meta.args && cmd.meta.args.length > 0) {
659
- data.args = cmd.meta.args.map((a) => {
660
- if (a.type === "enum") {
661
- 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 };
662
- }
663
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
664
- });
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
+ }));
665
896
  }
666
897
  return data;
667
898
  }
668
899
  function buildUmbrellaBody(extras) {
669
- const triggerBySkill = new Map(
670
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
671
- );
900
+ const triggersBySkill = /* @__PURE__ */ new Map();
901
+ for (const c of extras.availableCommands) {
902
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
903
+ triggers.push(c.meta.trigger);
904
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
905
+ }
672
906
  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}\``;
907
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
908
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
675
909
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
676
910
  });
677
911
  const sections = [
@@ -691,11 +925,17 @@ function buildUmbrellaBody(extras) {
691
925
  ...extras.hasQualityDoc ? [
692
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."
693
927
  ] : [],
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."
930
+ ] : [],
694
931
  "",
695
932
  "## Doc-first",
696
933
  "",
697
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.",
698
935
  "",
936
+ ...extras.hasIntents ? [
937
+ "- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
938
+ ] : [],
699
939
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
700
940
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
701
941
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -824,6 +1064,23 @@ function getRenderer(engine) {
824
1064
  return RENDERERS[engine];
825
1065
  }
826
1066
 
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) {
1077
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
1078
+ }
1079
+ }
1080
+ return `${lines.join("\n")}
1081
+ `;
1082
+ }
1083
+
827
1084
  // src/render.ts
828
1085
  var RenderError = class extends Error {
829
1086
  constructor(message) {
@@ -893,12 +1150,16 @@ function render(input) {
893
1150
  availableSkills: Array.from(exposedSkills.values()),
894
1151
  availableCommands: Array.from(exposedCmds.values()),
895
1152
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
896
- hasQualityDoc: input.hasQualityDoc === true
1153
+ hasQualityDoc: input.hasQualityDoc === true,
1154
+ hasIntents: (input.intentFiles?.length ?? 0) > 0
897
1155
  });
898
1156
  files.push({ path: "AGENTS.md", content: umbrellaContent });
899
1157
  if (engines.includes("claude-code")) {
900
1158
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
901
1159
  }
1160
+ if (input.intentFiles && input.intentFiles.length > 0) {
1161
+ files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
1162
+ }
902
1163
  return { files, warnings };
903
1164
  }
904
1165
 
@@ -930,7 +1191,8 @@ function planInit(args) {
930
1191
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
931
1192
  const projectSkills = loadProjectSkills(args.targetDir);
932
1193
  const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
933
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
1194
+ const intentFiles = loadIntentFiles(args.targetDir);
1195
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
934
1196
  return { engines, output };
935
1197
  }
936
1198
 
@@ -977,7 +1239,7 @@ var generatedFresh = {
977
1239
  const full = join8(repoRoot, file.path);
978
1240
  if (!existsSync7(full)) {
979
1241
  issues.push(issue(file.path, `generated file is missing; ${FIX}`));
980
- } else if (readFileSync5(full, "utf8") !== file.content) {
1242
+ } else if (readFileSync6(full, "utf8") !== file.content) {
981
1243
  issues.push(
982
1244
  issue(
983
1245
  file.path,
@@ -1008,7 +1270,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
1008
1270
  ".codex/",
1009
1271
  ".agents/",
1010
1272
  ".opencode/",
1011
- ".harness-manifest.json"
1273
+ ".harness-manifest.json",
1274
+ "docs/intents/README.md"
1012
1275
  ];
1013
1276
  function gitignoreEntries(text) {
1014
1277
  const entries = /* @__PURE__ */ new Set();
@@ -1067,9 +1330,211 @@ var gitignoreHarness = {
1067
1330
  }
1068
1331
  };
1069
1332
 
1333
+ // src/linters/intent-anchors.ts
1334
+ var intentAnchors = {
1335
+ id: "lint:intent-anchors",
1336
+ pillars: ["intents"],
1337
+ defaultSeverity: "error",
1338
+ suggestedSkills: ["/intent"],
1339
+ run(repoRoot) {
1340
+ const issues = [];
1341
+ for (const intentFile of readIntentFiles(repoRoot)) {
1342
+ for (const node of intentFile.nodes) {
1343
+ if (node.effectiveStatus === "deprecated") continue;
1344
+ for (const anchor of node.anchors) {
1345
+ if (trackedPathExists(repoRoot, anchor)) continue;
1346
+ issues.push({
1347
+ linter: this.id,
1348
+ severity: "error",
1349
+ file: intentFile.path,
1350
+ line: node.line,
1351
+ message: `"${node.title}": anchor matches no file: ${anchor}`
1352
+ });
1353
+ }
1354
+ }
1355
+ }
1356
+ return issues;
1357
+ }
1358
+ };
1359
+
1360
+ // src/linters/intent-graph.ts
1361
+ var intentGraph = {
1362
+ id: "lint:intent-graph",
1363
+ pillars: ["intents"],
1364
+ defaultSeverity: "warning",
1365
+ suggestedSkills: ["/intent"],
1366
+ run(repoRoot) {
1367
+ const intentFiles = readIntentFiles(repoRoot);
1368
+ const terminals = intentFiles.flatMap(
1369
+ (intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
1370
+ );
1371
+ const created = new Set(terminals.flatMap(({ node }) => node.creates));
1372
+ const issues = [];
1373
+ for (const { intentFile, node } of terminals) {
1374
+ for (const entity of node.requires) {
1375
+ if (created.has(entity)) continue;
1376
+ issues.push({
1377
+ linter: this.id,
1378
+ severity: "warning",
1379
+ file: intentFile.path,
1380
+ line: node.line,
1381
+ message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
1382
+ });
1383
+ }
1384
+ }
1385
+ return issues;
1386
+ }
1387
+ };
1388
+
1389
+ // src/linters/intent-util.ts
1390
+ import { posix } from "path";
1391
+ function intentFileSpecs(meta) {
1392
+ if (!meta) return [];
1393
+ return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
1394
+ }
1395
+ function resolveSpecPath(filePath, spec) {
1396
+ const withoutFragment = spec.split("#")[0] ?? "";
1397
+ return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
1398
+ }
1399
+
1400
+ // src/linters/intent-schema.ts
1401
+ var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
1402
+ var intentSchema = {
1403
+ id: "lint:intent-schema",
1404
+ pillars: ["intents"],
1405
+ defaultSeverity: "error",
1406
+ suggestedSkills: ["/intent"],
1407
+ run(repoRoot) {
1408
+ const issues = [];
1409
+ for (const intentFile of readIntentFiles(repoRoot)) {
1410
+ const report = (message, line) => {
1411
+ issues.push({
1412
+ linter: this.id,
1413
+ severity: "error",
1414
+ file: intentFile.path,
1415
+ ...line !== void 0 ? { line } : {},
1416
+ message
1417
+ });
1418
+ };
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))) {
1422
+ report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
1423
+ }
1424
+ }
1425
+ for (const node of intentFile.nodes) {
1426
+ const at = (message) => report(`"${node.title}": ${message}`, node.line);
1427
+ for (const { key, line } of node.unknownFields) {
1428
+ report(
1429
+ DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
1430
+ line
1431
+ );
1432
+ }
1433
+ if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
1434
+ report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
1435
+ }
1436
+ if (!node.isTerminal) {
1437
+ for (const field of TERMINAL_FIELDS) {
1438
+ const line = node.fieldLines[field];
1439
+ if (line !== void 0) {
1440
+ report(
1441
+ `"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
1442
+ line
1443
+ );
1444
+ }
1445
+ }
1446
+ continue;
1447
+ }
1448
+ if (Object.keys(node.fieldLines).length === 0) {
1449
+ at("a terminal intent carries at least one field");
1450
+ continue;
1451
+ }
1452
+ if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
1453
+ at("an `implemented` intent needs `anchors:`");
1454
+ }
1455
+ if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
1456
+ at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
1457
+ }
1458
+ }
1459
+ }
1460
+ return issues;
1461
+ }
1462
+ };
1463
+
1464
+ // src/linters/intent-vocabulary.ts
1465
+ var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
1466
+ var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
1467
+ function entitySlug(term) {
1468
+ return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
1469
+ }
1470
+ function vocabularyOf(specText) {
1471
+ const lines = maskFencedCode(specText.split(/\r?\n/));
1472
+ let depth;
1473
+ let terms;
1474
+ for (const line of lines) {
1475
+ const heading = parseHeading(line);
1476
+ if (depth !== void 0) {
1477
+ if (heading && heading.depth <= depth) break;
1478
+ const term = TERM.exec(line)?.[1];
1479
+ if (term) terms?.add(entitySlug(term));
1480
+ continue;
1481
+ }
1482
+ if (heading && VOCABULARY_HEADING.test(line)) {
1483
+ depth = heading.depth;
1484
+ terms = /* @__PURE__ */ new Set();
1485
+ }
1486
+ }
1487
+ return terms;
1488
+ }
1489
+ var intentVocabulary = {
1490
+ id: "lint:intent-vocabulary",
1491
+ pillars: ["intents"],
1492
+ defaultSeverity: "error",
1493
+ suggestedSkills: ["/spec"],
1494
+ run(repoRoot) {
1495
+ const issues = [];
1496
+ for (const intentFile of readIntentFiles(repoRoot)) {
1497
+ const used = intentFile.nodes.flatMap(
1498
+ (node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
1499
+ );
1500
+ if (used.length === 0) continue;
1501
+ const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
1502
+ if (specs.length === 0) continue;
1503
+ const entities = /* @__PURE__ */ new Set();
1504
+ let hasVocabulary = false;
1505
+ for (const spec of specs) {
1506
+ const terms = vocabularyOf(readText(repoRoot, spec));
1507
+ if (!terms) continue;
1508
+ hasVocabulary = true;
1509
+ for (const term of terms) entities.add(term);
1510
+ }
1511
+ if (!hasVocabulary) {
1512
+ issues.push({
1513
+ linter: this.id,
1514
+ severity: "warning",
1515
+ file: intentFile.path,
1516
+ message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
1517
+ });
1518
+ continue;
1519
+ }
1520
+ for (const { entity, node } of used) {
1521
+ if (entities.has(entity)) continue;
1522
+ issues.push({
1523
+ linter: this.id,
1524
+ severity: "error",
1525
+ file: intentFile.path,
1526
+ line: node.line,
1527
+ message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
1528
+ });
1529
+ }
1530
+ }
1531
+ return issues;
1532
+ }
1533
+ };
1534
+
1070
1535
  // src/linters/orphan-decisions.ts
1071
- import { basename as basename2 } from "path";
1072
- import fg5 from "fast-glob";
1536
+ import { basename as basename3 } from "path";
1537
+ import fg4 from "fast-glob";
1073
1538
  var orphanDecisions = {
1074
1539
  id: "lint:orphan-decisions",
1075
1540
  pillars: ["decisions"],
@@ -1080,7 +1545,7 @@ var orphanDecisions = {
1080
1545
  const issues = [];
1081
1546
  const adrs = listMarkdown(repoRoot, "docs/decisions");
1082
1547
  if (adrs.length === 0) return issues;
1083
- const otherDocs = fg5.sync("**/*.md", {
1548
+ const otherDocs = fg4.sync("**/*.md", {
1084
1549
  cwd: repoRoot,
1085
1550
  absolute: false,
1086
1551
  ignore: [
@@ -1097,7 +1562,7 @@ var orphanDecisions = {
1097
1562
  });
1098
1563
  const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
1099
1564
  for (const adr of adrs) {
1100
- const filename = basename2(adr);
1565
+ const filename = basename3(adr);
1101
1566
  const stem = filename.replace(/\.md$/, "");
1102
1567
  const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
1103
1568
  if (!referenced) {
@@ -1273,33 +1738,42 @@ var specTechAgnostic = {
1273
1738
  };
1274
1739
 
1275
1740
  // src/linters/tracks-drift.ts
1276
- import fg6 from "fast-glob";
1741
+ import fg5 from "fast-glob";
1277
1742
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
1743
+ var INTENTS_DIR2 = "docs/intents";
1278
1744
  var DEFAULT_DRIFT_THRESHOLD = 10;
1279
1745
  function expandGlob(repoRoot, pattern) {
1280
1746
  if (pattern.includes("*")) {
1281
- return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
1747
+ return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
1282
1748
  }
1283
1749
  return [pattern];
1284
1750
  }
1751
+ function trackedPaths(dir, file, text, data) {
1752
+ if (dir === INTENTS_DIR2) {
1753
+ const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
1754
+ return anchors.length > 0 ? [...new Set(anchors)] : void 0;
1755
+ }
1756
+ return Array.isArray(data.tracks) ? data.tracks : void 0;
1757
+ }
1285
1758
  var tracksDrift = {
1286
1759
  id: "lint:tracks-drift",
1287
- pillars: ["handbook", "tests", "workflow"],
1760
+ pillars: ["handbook", "tests", "workflow", "intents"],
1288
1761
  defaultSeverity: "warning",
1289
1762
  suggestedSkills: ["/drift", "/handbook"],
1290
1763
  run(repoRoot) {
1291
1764
  const issues = [];
1292
- for (const dir of TRACKED_DIRS2) {
1765
+ for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
1293
1766
  const files = listMarkdown(repoRoot, dir);
1294
1767
  for (const f of files) {
1295
1768
  const text = readText(repoRoot, f);
1296
1769
  const { data } = parseFrontmatter(text);
1297
- if (!Array.isArray(data.tracks)) continue;
1770
+ const tracks = trackedPaths(dir, f, text, data);
1771
+ if (!tracks) continue;
1298
1772
  const docCommit = gitLastCommitForPath(repoRoot, f);
1299
1773
  if (!docCommit) continue;
1300
1774
  const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
1301
1775
  let driftCount = 0;
1302
- for (const tracked of data.tracks) {
1776
+ for (const tracked of tracks) {
1303
1777
  if (typeof tracked !== "string") continue;
1304
1778
  const targets = expandGlob(repoRoot, tracked);
1305
1779
  for (const t of targets.length > 0 ? targets : [tracked]) {
@@ -1336,6 +1810,10 @@ var ALL_LINTERS = [
1336
1810
  orphanDecisions,
1337
1811
  gitignoreHarness,
1338
1812
  qualitySchema,
1813
+ intentSchema,
1814
+ intentAnchors,
1815
+ intentVocabulary,
1816
+ intentGraph,
1339
1817
  generatedFresh
1340
1818
  ];
1341
1819
  function runLinters(repoRoot, opts = {}) {
@@ -1391,7 +1869,7 @@ function formatReportText(report) {
1391
1869
  }
1392
1870
 
1393
1871
  // src/cli/check.ts
1394
- import { existsSync as existsSync8, readFileSync as readFileSync6 } from "fs";
1872
+ import { existsSync as existsSync8, readFileSync as readFileSync7 } from "fs";
1395
1873
  import { join as join9 } from "path";
1396
1874
  var REQUIRED_DIRS2 = [
1397
1875
  "docs/spec",
@@ -1414,7 +1892,7 @@ function checkCommand(repoRoot) {
1414
1892
  if (!existsSync8(gitignorePath)) {
1415
1893
  issues.push(".gitignore missing at repo root");
1416
1894
  } else {
1417
- const text = readFileSync6(gitignorePath, "utf8");
1895
+ const text = readFileSync7(gitignorePath, "utf8");
1418
1896
  for (const entry of missingGitignoreEntries(text)) {
1419
1897
  issues.push(`.gitignore missing entry: ${entry}`);
1420
1898
  }
@@ -1430,7 +1908,7 @@ import { existsSync as existsSync12, mkdirSync as mkdirSync2, rmSync, writeFileS
1430
1908
  import { dirname as dirname7, join as join14, resolve as resolve8 } from "path";
1431
1909
 
1432
1910
  // src/cli/uninstall.ts
1433
- import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync, rmdirSync, unlinkSync } from "fs";
1911
+ import { existsSync as existsSync9, readFileSync as readFileSync8, readdirSync as readdirSync2, rmdirSync, unlinkSync } from "fs";
1434
1912
  import { dirname as dirname4, join as join10, relative as relative2, resolve as resolve5 } from "path";
1435
1913
  function uninstallCommand(args) {
1436
1914
  const root = resolve5(args.targetDir);
@@ -1447,7 +1925,7 @@ function uninstallCommand(args) {
1447
1925
  const modified = files.filter((file) => {
1448
1926
  const hash = manifest.fileHashes?.[file];
1449
1927
  const full = join10(root, file);
1450
- return hash !== void 0 && existsSync9(full) && hashContent(readFileSync7(full)) !== hash;
1928
+ return hash !== void 0 && existsSync9(full) && hashContent(readFileSync8(full)) !== hash;
1451
1929
  });
1452
1930
  const ownedFiles = files.filter((file) => !modified.includes(file));
1453
1931
  const { filesRemoved, dirsPruned, missing } = removeRenderedFiles(root, ownedFiles);
@@ -1489,7 +1967,7 @@ function pruneEmptyDirs(root, leaves) {
1489
1967
  const sorted = [...candidates].sort((a, b) => b.length - a.length);
1490
1968
  for (const dir of sorted) {
1491
1969
  if (!existsSync9(dir)) continue;
1492
- if (readdirSync(dir).length > 0) continue;
1970
+ if (readdirSync2(dir).length > 0) continue;
1493
1971
  rmdirSync(dir);
1494
1972
  pruned.push(relative2(root, dir));
1495
1973
  }
@@ -1505,22 +1983,22 @@ import {
1505
1983
  lstatSync as lstatSync2,
1506
1984
  mkdirSync,
1507
1985
  openSync,
1508
- readFileSync as readFileSync8,
1509
- readdirSync as readdirSync2,
1986
+ readFileSync as readFileSync9,
1987
+ readdirSync as readdirSync3,
1510
1988
  realpathSync as realpathSync2,
1511
1989
  rmdirSync as rmdirSync2,
1512
1990
  unlinkSync as unlinkSync2,
1513
1991
  writeFileSync as writeFileSync2
1514
1992
  } from "fs";
1515
1993
  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";
1994
+ import { basename as basename4, dirname as dirname5, isAbsolute as isAbsolute3, join as join11, relative as relative3, resolve as resolve6, sep } from "path";
1517
1995
  var MANIFEST_PATH = ".harness-manifest.json";
1518
1996
  var PRIVATE_FILES = /* @__PURE__ */ new Set([MANIFEST_PATH]);
1519
1997
  function canonicalRoot(root) {
1520
1998
  let ancestor = resolve6(root);
1521
1999
  const missing = [];
1522
2000
  while (!lstatSync2(ancestor, { throwIfNoEntry: false })) {
1523
- missing.unshift(basename3(ancestor));
2001
+ missing.unshift(basename4(ancestor));
1524
2002
  ancestor = dirname5(ancestor);
1525
2003
  }
1526
2004
  return join11(realpathSync2(ancestor), ...missing);
@@ -1580,7 +2058,7 @@ function saveSnapshot(root, paths, backup) {
1580
2058
  entries.push({ path, exists: false });
1581
2059
  continue;
1582
2060
  }
1583
- const content = readFileSync8(full);
2061
+ const content = readFileSync9(full);
1584
2062
  writeBackupFile(join11(backup, "files", path), content);
1585
2063
  entries.push({
1586
2064
  path,
@@ -1611,8 +2089,8 @@ function rollback(root, backup, entries, touched, createdDirectories) {
1611
2089
  if (current) unlinkSync2(full);
1612
2090
  continue;
1613
2091
  }
1614
- const original = readFileSync8(join11(backup, "files", path));
1615
- if (!current || !readFileSync8(full).equals(original)) {
2092
+ const original = readFileSync9(join11(backup, "files", path));
2093
+ if (!current || !readFileSync9(full).equals(original)) {
1616
2094
  if (current) unlinkSync2(full);
1617
2095
  writeFileSync2(full, original, { mode: 384 });
1618
2096
  }
@@ -1623,7 +2101,7 @@ function rollback(root, backup, entries, touched, createdDirectories) {
1623
2101
  }
1624
2102
  for (const directory of [...createdDirectories].reverse()) {
1625
2103
  try {
1626
- if (readdirSync2(directory).length === 0) rmdirSync2(directory);
2104
+ if (readdirSync3(directory).length === 0) rmdirSync2(directory);
1627
2105
  } catch (error) {
1628
2106
  errors.push(`${directory}: ${errorMessage(error)}`);
1629
2107
  }
@@ -1678,12 +2156,12 @@ function applyUpdateTransaction(root, writes, removals, backupDir) {
1678
2156
  }
1679
2157
 
1680
2158
  // src/cli/update.ts
1681
- import { existsSync as existsSync11, readFileSync as readFileSync10 } from "fs";
2159
+ import { existsSync as existsSync11, readFileSync as readFileSync11, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
1682
2160
  import { dirname as dirname6, join as join13, resolve as resolve7 } from "path";
1683
2161
  import { isDeepStrictEqual } from "util";
1684
2162
 
1685
2163
  // src/cli/update-manifest.ts
1686
- import { existsSync as existsSync10, readFileSync as readFileSync9 } from "fs";
2164
+ import { existsSync as existsSync10, readFileSync as readFileSync10 } from "fs";
1687
2165
  import { join as join12 } from "path";
1688
2166
  import { z as z4 } from "zod";
1689
2167
  var EngineSchema = z4.enum(ENGINES);
@@ -1699,7 +2177,7 @@ function readUpdateInstallation(root) {
1699
2177
  if (!existsSync10(join12(root, MANIFEST_FILENAME))) {
1700
2178
  throw new Error("no harness manifest found; use init for a new installation");
1701
2179
  }
1702
- const raw = JSON.parse(readFileSync9(join12(root, MANIFEST_FILENAME), "utf8"));
2180
+ const raw = JSON.parse(readFileSync10(join12(root, MANIFEST_FILENAME), "utf8"));
1703
2181
  const sourceVersion = String(raw?.version);
1704
2182
  let manifest;
1705
2183
  if (["1", "2", "3"].includes(sourceVersion)) {
@@ -1724,7 +2202,7 @@ function readUpdateInstallation(root) {
1724
2202
  var LEGACY_HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
1725
2203
  var LEGACY_HOOK_MARKER = "@vaubaan/harness stop-hook";
1726
2204
  function currentContent(root, path) {
1727
- return existsSync11(join13(root, path)) ? readFileSync10(join13(root, path), "utf8") : void 0;
2205
+ return existsSync11(join13(root, path)) ? readFileSync11(join13(root, path), "utf8") : void 0;
1728
2206
  }
1729
2207
  function checkArtifactConflicts(root, previous, writes, removals) {
1730
2208
  const desired = new Map(writes.map((file) => [file.path, file.content]));
@@ -1754,6 +2232,27 @@ function releaseLegacyPaths(previous, warnings) {
1754
2232
  if (released.length === 0) return previous;
1755
2233
  return { ...previous, files: previous.files.filter((path) => !released.includes(path)) };
1756
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
+ }
1757
2256
  function legacyHookWarnings(root) {
1758
2257
  const warnings = [];
1759
2258
  for (const path of LEGACY_HOOK_FILES) {
@@ -1770,7 +2269,7 @@ function planInstallation(args, settings) {
1770
2269
  const root = resolve7(args.targetDir);
1771
2270
  const { engines } = settings;
1772
2271
  const warnings = [];
1773
- const previous = releaseLegacyPaths(settings.previous, warnings);
2272
+ const previous = carryMovedPaths(root, releaseLegacyPaths(settings.previous, warnings), warnings);
1774
2273
  const preserved = [
1775
2274
  .../* @__PURE__ */ new Set([...previous.preservedFiles ?? [], ...args.preserveFiles ?? []])
1776
2275
  ].sort();
@@ -1786,7 +2285,7 @@ function planInstallation(args, settings) {
1786
2285
  const disablePath = join13(overridesDir, ".harness-overrides", "disable.yaml");
1787
2286
  if (existsSync11(disablePath)) {
1788
2287
  try {
1789
- DisableYamlSchema.parse(parseYAML(readFileSync10(disablePath, "utf8")));
2288
+ DisableYamlSchema.parse(parseYAML(readFileSync11(disablePath, "utf8")));
1790
2289
  } catch {
1791
2290
  throw new Error(`invalid override selection: ${disablePath}`);
1792
2291
  }
@@ -2007,7 +2506,7 @@ program.command("check").description("Verify repo layout: doc pillars present an
2007
2506
  });
2008
2507
  program.command("lint").description("Run all mechanical linters and exit non-zero on errors").option(
2009
2508
  "--pillar <pillar>",
2010
- "filter by pillar (spec, decisions, handbook, tests, workflow, quality)"
2509
+ "filter by pillar (spec, decisions, handbook, tests, workflow, quality, intents)"
2011
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) => {
2012
2511
  const repoRoot = resolve9(opts.cwd ?? ".");
2013
2512
  const only = parseList(opts.only);