@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.
@@ -10,6 +10,12 @@ function fileExists(repoRoot, relativePath) {
10
10
  function readText(repoRoot, relativePath) {
11
11
  return readFileSync(join(repoRoot, relativePath), "utf8");
12
12
  }
13
+ function trackedPathExists(repoRoot, pattern) {
14
+ if (pattern.includes("*")) {
15
+ return fg.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
16
+ }
17
+ return existsSync(join(repoRoot, pattern));
18
+ }
13
19
  function listMarkdown(repoRoot, dir) {
14
20
  const cwd = join(repoRoot, dir);
15
21
  if (!existsSync(cwd)) return [];
@@ -293,16 +299,7 @@ var docLayout = {
293
299
  };
294
300
 
295
301
  // src/linters/frontmatter-tracks.ts
296
- import { existsSync as existsSync3 } from "fs";
297
- import { join as join3 } from "path";
298
- import fg3 from "fast-glob";
299
302
  var TRACKED_DIRS = ["docs/handbook", "docs/tests", "docs/workflow"];
300
- function trackedPathExists(repoRoot, pattern) {
301
- if (pattern.includes("*")) {
302
- return fg3.sync(pattern, { cwd: repoRoot, absolute: false }).length > 0;
303
- }
304
- return existsSync3(join3(repoRoot, pattern));
305
- }
306
303
  var frontmatterTracks = {
307
304
  id: "lint:frontmatter-tracks",
308
305
  pillars: ["handbook", "tests", "workflow"],
@@ -350,13 +347,21 @@ var frontmatterTracks = {
350
347
  };
351
348
 
352
349
  // src/linters/generated-fresh.ts
353
- import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
350
+ import { existsSync as existsSync7, readFileSync as readFileSync6 } from "fs";
354
351
  import { join as join8, resolve as resolve4 } from "path";
355
352
 
356
353
  // src/cli/managed-paths.ts
357
354
  import { lstatSync, realpathSync, statSync as statSync2 } from "fs";
358
- import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join4, resolve as resolve2, win32 } from "path";
359
- var MANAGED_FILES = /* @__PURE__ */ new Set(["AGENTS.md", "CLAUDE.md", ".harness-manifest.json"]);
355
+ import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join3, resolve as resolve2, win32 } from "path";
356
+ var MANAGED_FILES = /* @__PURE__ */ new Set([
357
+ "AGENTS.md",
358
+ "CLAUDE.md",
359
+ ".harness-manifest.json",
360
+ // Index of the optional intents pillar, rendered while an intent file exists.
361
+ "docs/intents/README.md",
362
+ // Its 2.2 location, kept managed so `update` can remove it (see MOVED_PATHS).
363
+ "docs/journeys/README.md"
364
+ ]);
360
365
  var RELEASED_PATHS = [
361
366
  ".mcp.json",
362
367
  ".codex/config.toml",
@@ -389,7 +394,7 @@ function canonicalTargetRoot(root) {
389
394
  if (!statSync2(canonical).isDirectory()) {
390
395
  throw new Error(`harness target is not a directory: ${root}`);
391
396
  }
392
- return join4(canonical, ...missing);
397
+ return join3(canonical, ...missing);
393
398
  }
394
399
  function assertManagedLocation(path) {
395
400
  const invalidSegment = path.split("/").some((part) => part === "" || part === "." || part === "..");
@@ -404,7 +409,7 @@ function assertNoSymbolicComponents(root, path) {
404
409
  const parts = path.split("/");
405
410
  let current = root;
406
411
  for (const [index, part] of parts.entries()) {
407
- current = join4(current, part);
412
+ current = join3(current, part);
408
413
  const info = lstatSync(current, { throwIfNoEntry: false });
409
414
  if (!info) return;
410
415
  if (info.isSymbolicLink()) {
@@ -424,8 +429,8 @@ function assertManagedPaths(root, files) {
424
429
 
425
430
  // src/cli/manifest.ts
426
431
  import { createHash } from "crypto";
427
- import { chmodSync, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync } from "fs";
428
- import { join as join5 } from "path";
432
+ import { chmodSync, existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync } from "fs";
433
+ import { join as join4 } from "path";
429
434
  import { z } from "zod";
430
435
  var MANIFEST_FILENAME = ".harness-manifest.json";
431
436
  var MANIFEST_VERSION = "6";
@@ -440,12 +445,12 @@ var ManifestSchema = z.object({
440
445
  preservedFiles: z.array(z.string()).optional()
441
446
  });
442
447
  function manifestPath(targetDir) {
443
- return join5(targetDir, MANIFEST_FILENAME);
448
+ return join4(targetDir, MANIFEST_FILENAME);
444
449
  }
445
450
  function readManifest(targetDir) {
446
451
  assertManagedPaths(targetDir, [MANIFEST_FILENAME]);
447
452
  const path = manifestPath(targetDir);
448
- if (!existsSync4(path)) return null;
453
+ if (!existsSync3(path)) return null;
449
454
  const raw = JSON.parse(readFileSync2(path, "utf8"));
450
455
  return ManifestSchema.parse(raw);
451
456
  }
@@ -456,9 +461,9 @@ import { dirname as dirname3, join as join7, resolve as resolve3 } from "path";
456
461
  import { fileURLToPath } from "url";
457
462
 
458
463
  // src/loader.ts
459
- import { existsSync as existsSync5, readFileSync as readFileSync4 } from "fs";
460
- import { join as join6 } from "path";
461
- import fg4 from "fast-glob";
464
+ import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
465
+ import { join as join5 } from "path";
466
+ import fg3 from "fast-glob";
462
467
  import { z as z3 } from "zod";
463
468
 
464
469
  // src/parser/common.ts
@@ -493,12 +498,16 @@ var CmdArgEnumSchema = z2.object({
493
498
  name: z2.string().min(1),
494
499
  type: z2.literal("enum"),
495
500
  values: z2.array(z2.string()).min(1),
496
- default: z2.string().optional()
501
+ default: z2.string().optional(),
502
+ /** False when the command runs without the argument. Defaults to true. */
503
+ required: z2.boolean().optional()
497
504
  }).strict();
498
505
  var CmdArgStringSchema = z2.object({
499
506
  name: z2.string().min(1),
500
507
  type: z2.literal("string"),
501
- default: z2.string().optional()
508
+ default: z2.string().optional(),
509
+ /** False when the command runs without the argument. Defaults to true. */
510
+ required: z2.boolean().optional()
502
511
  }).strict();
503
512
  var CmdArgSchema = z2.discriminatedUnion("type", [CmdArgEnumSchema, CmdArgStringSchema]);
504
513
  var CmdFrontmatterSchema = z2.object({
@@ -508,9 +517,18 @@ var CmdFrontmatterSchema = z2.object({
508
517
  args: z2.array(CmdArgSchema).optional(),
509
518
  description: z2.string().min(1)
510
519
  }).strict();
520
+ var INTENT_STATUSES = ["proposed", "implemented", "deprecated"];
521
+ var IntentFrontmatterSchema = z2.object({
522
+ title: z2.string().min(1),
523
+ status: z2.enum(INTENT_STATUSES),
524
+ actors: z2.array(z2.string().min(1)).min(1),
525
+ spec: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]),
526
+ last_reviewed: z2.union([z2.date(), z2.string().min(1)])
527
+ }).strict();
511
528
  var Schemas = {
512
529
  Skill: SkillFrontmatterSchema,
513
- Cmd: CmdFrontmatterSchema
530
+ Cmd: CmdFrontmatterSchema,
531
+ Intent: IntentFrontmatterSchema
514
532
  };
515
533
  var ParseError = class extends Error {
516
534
  constructor(file, issues) {
@@ -558,31 +576,31 @@ function parseYAML(source) {
558
576
  // src/loader.ts
559
577
  var DisableYamlSchema = z3.object({ disable: z3.array(z3.string()).optional() }).passthrough();
560
578
  function loadHarness(packageDir, opts = {}) {
561
- const skillsDir = opts.skillsDir ?? join6(packageDir, "skills");
562
- const commandsDir = opts.commandsDir ?? join6(packageDir, "commands");
563
- const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
564
- const cmdFiles = fg4.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
579
+ const skillsDir = opts.skillsDir ?? join5(packageDir, "skills");
580
+ const commandsDir = opts.commandsDir ?? join5(packageDir, "commands");
581
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
582
+ const cmdFiles = fg3.sync("*.cmd.md", { cwd: commandsDir, absolute: true });
565
583
  return {
566
584
  skills: skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8"))),
567
585
  cmds: cmdFiles.map((f) => parseCmd(f, readFileSync4(f, "utf8")))
568
586
  };
569
587
  }
570
588
  function loadProjectSkills(targetDir) {
571
- const skillsDir = join6(targetDir, "docs", "skills");
572
- if (!existsSync5(skillsDir)) return [];
573
- const skillFiles = fg4.sync("*.skill.md", { cwd: skillsDir, absolute: true });
589
+ const skillsDir = join5(targetDir, "docs", "skills");
590
+ if (!existsSync4(skillsDir)) return [];
591
+ const skillFiles = fg3.sync("*.skill.md", { cwd: skillsDir, absolute: true });
574
592
  return skillFiles.map((f) => parseSkill(f, readFileSync4(f, "utf8")));
575
593
  }
576
594
  function loadOverrides(worktreeDir) {
577
- const overridesDir = join6(worktreeDir, ".harness-overrides");
578
- if (!existsSync5(overridesDir)) return void 0;
595
+ const overridesDir = join5(worktreeDir, ".harness-overrides");
596
+ if (!existsSync4(overridesDir)) return void 0;
579
597
  const added = loadHarness(overridesDir, {
580
- skillsDir: join6(overridesDir, "skills"),
581
- commandsDir: join6(overridesDir, "commands")
598
+ skillsDir: join5(overridesDir, "skills"),
599
+ commandsDir: join5(overridesDir, "commands")
582
600
  });
583
- const disablePath = join6(overridesDir, "disable.yaml");
601
+ const disablePath = join5(overridesDir, "disable.yaml");
584
602
  let disable = [];
585
- if (existsSync5(disablePath)) {
603
+ if (existsSync4(disablePath)) {
586
604
  try {
587
605
  const parsed = DisableYamlSchema.safeParse(parseYAML(readFileSync4(disablePath, "utf8")));
588
606
  if (parsed.success && parsed.data.disable) {
@@ -594,6 +612,214 @@ function loadOverrides(worktreeDir) {
594
612
  return { add: added, disable };
595
613
  }
596
614
 
615
+ // src/parser/intent.ts
616
+ import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync, statSync as statSync3 } from "fs";
617
+ import { basename as basename2, join as join6 } from "path";
618
+ import matter3 from "gray-matter";
619
+ var INTENTS_DIR = "docs/intents";
620
+ var INTENTS_INDEX_PATH = `${INTENTS_DIR}/README.md`;
621
+ var NODE_FIELDS = [
622
+ "status",
623
+ "spec",
624
+ "anchors",
625
+ "acceptance",
626
+ "requires",
627
+ "creates"
628
+ ];
629
+ var TERMINAL_FIELDS = [
630
+ "anchors",
631
+ "acceptance",
632
+ "requires",
633
+ "creates"
634
+ ];
635
+ var MASKED_LINE = "\0";
636
+ var FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
637
+ var HEADING_RE = /^(#{1,6})[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
638
+ var FIELD_RE = /^([a-z][a-z-]*):\s*(.*)$/;
639
+ var LIST_ITEM_RE = /^\s*-\s+(.*)$/;
640
+ function maskFencedCode(lines) {
641
+ let fence;
642
+ return lines.map((line) => {
643
+ const m = FENCE_RE.exec(line);
644
+ if (fence !== void 0) {
645
+ if (m?.[1] && m[1][0] === fence[0] && m[1].length >= fence.length) fence = void 0;
646
+ return MASKED_LINE;
647
+ }
648
+ if (m?.[1]) {
649
+ fence = m[1];
650
+ return MASKED_LINE;
651
+ }
652
+ return line;
653
+ });
654
+ }
655
+ function parseHeading(line) {
656
+ const m = HEADING_RE.exec(line);
657
+ if (!m?.[1] || !m[2]) return void 0;
658
+ return { depth: m[1].length, title: m[2] };
659
+ }
660
+ function splitList(value) {
661
+ return value.split(",").map((v) => v.trim()).filter(Boolean);
662
+ }
663
+ function bodyStart(lines) {
664
+ if (lines[0]?.trim() !== "---") return 0;
665
+ for (let i = 1; i < lines.length; i++) {
666
+ const l = lines[i]?.trim();
667
+ if (l === "---" || l === "...") return i + 1;
668
+ }
669
+ return lines.length;
670
+ }
671
+ function parseFrontmatter2(text, errors) {
672
+ let data;
673
+ try {
674
+ data = matter3(text).data;
675
+ } catch (error) {
676
+ const reason = error instanceof Error ? error.message.split("\n")[0] : String(error);
677
+ errors.push({ line: 1, message: `invalid frontmatter YAML: ${reason}` });
678
+ return void 0;
679
+ }
680
+ const result = Schemas.Intent.safeParse(data);
681
+ if (result.success) return result.data;
682
+ for (const issue of result.error.issues) {
683
+ const where = issue.path.length ? ` \`${issue.path.join(".")}\`` : "";
684
+ errors.push({ line: 1, message: `frontmatter${where}: ${issue.message}` });
685
+ }
686
+ return void 0;
687
+ }
688
+ function newNode(title, level, line) {
689
+ return {
690
+ title,
691
+ level,
692
+ line,
693
+ isTerminal: true,
694
+ fieldLines: {},
695
+ anchors: [],
696
+ acceptance: [],
697
+ requires: [],
698
+ creates: [],
699
+ unknownFields: []
700
+ };
701
+ }
702
+ function parseFields(node, lines, from, to, errors) {
703
+ let lastKey;
704
+ for (let i = from; i < to; i++) {
705
+ const line = lines[i] ?? "";
706
+ if (line.trim() === "") continue;
707
+ const lineNo = i + 1;
708
+ const field = FIELD_RE.exec(line.trimEnd());
709
+ if (field?.[1] !== void 0) {
710
+ const key = field[1];
711
+ const value = (field[2] ?? "").trim();
712
+ lastKey = key;
713
+ if (!NODE_FIELDS.includes(key)) {
714
+ node.unknownFields.push({ key, line: lineNo });
715
+ continue;
716
+ }
717
+ const known = key;
718
+ node.fieldLines[known] = lineNo;
719
+ if (known === "status") {
720
+ if (INTENT_STATUSES.includes(value)) {
721
+ node.status = value;
722
+ } else {
723
+ errors.push({
724
+ line: lineNo,
725
+ message: `invalid status \`${value}\` (expected ${INTENT_STATUSES.join(" | ")})`
726
+ });
727
+ }
728
+ } else if (known === "spec") {
729
+ node.spec = value;
730
+ } else if (known === "acceptance") {
731
+ if (value) node.acceptance.push(value);
732
+ } else {
733
+ node[known] = splitList(value);
734
+ }
735
+ continue;
736
+ }
737
+ const item = LIST_ITEM_RE.exec(line);
738
+ if (lastKey === "acceptance" && item) {
739
+ const text = (item[1] ?? "").trim();
740
+ if (text) node.acceptance.push(text);
741
+ continue;
742
+ }
743
+ return;
744
+ }
745
+ }
746
+ function parseIntentFile(relPath, text) {
747
+ const errors = [];
748
+ const meta = parseFrontmatter2(text, errors);
749
+ const lines = maskFencedCode(text.split(/\r?\n/));
750
+ const start = bodyStart(lines);
751
+ const headings = [];
752
+ for (let i = start; i < lines.length; i++) {
753
+ const h = parseHeading(lines[i] ?? "");
754
+ if (h) headings.push({ index: i, ...h });
755
+ }
756
+ const h1 = headings.find((h) => h.depth === 1);
757
+ let statement;
758
+ if (h1) {
759
+ const paragraph = [];
760
+ for (let i = h1.index + 1; i < lines.length; i++) {
761
+ const line = lines[i] ?? "";
762
+ if (line.trim() === "") {
763
+ if (paragraph.length) break;
764
+ continue;
765
+ }
766
+ if (line === MASKED_LINE || parseHeading(line)) break;
767
+ paragraph.push(line.trim());
768
+ }
769
+ if (paragraph.length) statement = paragraph.join(" ");
770
+ }
771
+ const nodes = [];
772
+ const stack = [];
773
+ for (const [k, h] of headings.entries()) {
774
+ if (h.depth < 2) continue;
775
+ const node = newNode(h.title, h.depth - 1, h.index + 1);
776
+ while (stack.length) {
777
+ const top = nodes[stack[stack.length - 1]];
778
+ if (top && top.level < node.level) break;
779
+ stack.pop();
780
+ }
781
+ const parentIndex = stack[stack.length - 1];
782
+ if (parentIndex !== void 0) {
783
+ node.parent = parentIndex;
784
+ const parent = nodes[parentIndex];
785
+ if (parent) parent.isTerminal = false;
786
+ }
787
+ const next = headings[k + 1];
788
+ parseFields(node, lines, h.index + 1, next ? next.index : lines.length, errors);
789
+ const inherited = parentIndex !== void 0 ? nodes[parentIndex]?.effectiveStatus : meta?.status;
790
+ node.effectiveStatus = node.status ?? inherited;
791
+ stack.push(nodes.length);
792
+ nodes.push(node);
793
+ }
794
+ const title = meta?.title ?? h1?.title ?? basename2(relPath, ".md");
795
+ return { ...meta ? { meta } : {}, title, ...statement ? { statement } : {}, nodes, errors };
796
+ }
797
+ function listIntentFiles(targetDir) {
798
+ const dir = join6(targetDir, INTENTS_DIR);
799
+ if (!existsSync5(dir) || !statSync3(dir).isDirectory()) return [];
800
+ return readdirSync(dir).filter((f) => f.endsWith(".md") && f !== "README.md").filter((f) => statSync3(join6(dir, f)).isFile()).sort();
801
+ }
802
+ function readIntentFiles(targetDir) {
803
+ return listIntentFiles(targetDir).map((file) => {
804
+ const path = `${INTENTS_DIR}/${file}`;
805
+ const text = readFileSync5(join6(targetDir, path), "utf8");
806
+ return { path, file, ...parseIntentFile(path, text) };
807
+ });
808
+ }
809
+ function loadIntentFiles(targetDir) {
810
+ const intentFiles = readIntentFiles(targetDir);
811
+ const problems = intentFiles.flatMap(
812
+ (j) => j.errors.map((e) => ` - ${j.path}${e.line !== void 0 ? `:${e.line}` : ""}: ${e.message}`)
813
+ );
814
+ if (problems.length) {
815
+ throw new Error(
816
+ `invalid intents (run \`npx @vaubaan/harness lint --pillar intents\`):
817
+ ${problems.join("\n")}`
818
+ );
819
+ }
820
+ return intentFiles;
821
+ }
822
+
597
823
  // src/renderers/common.ts
598
824
  import { stringify as yamlStringify } from "yaml";
599
825
  function checkSkillCapabilities(skill, engine) {
@@ -641,22 +867,26 @@ function frontmatterDataForCmd(cmd) {
641
867
  description: cmd.meta.description
642
868
  };
643
869
  if (cmd.meta.args && cmd.meta.args.length > 0) {
644
- data.args = cmd.meta.args.map((a) => {
645
- if (a.type === "enum") {
646
- return a.default !== void 0 ? { name: a.name, type: a.type, values: a.values, default: a.default } : { name: a.name, type: a.type, values: a.values };
647
- }
648
- return a.default !== void 0 ? { name: a.name, type: a.type, default: a.default } : { name: a.name, type: a.type };
649
- });
870
+ data.args = cmd.meta.args.map((a) => ({
871
+ name: a.name,
872
+ type: a.type,
873
+ ...a.type === "enum" ? { values: a.values } : {},
874
+ ...a.default !== void 0 ? { default: a.default } : {},
875
+ ...a.required === false ? { required: false } : {}
876
+ }));
650
877
  }
651
878
  return data;
652
879
  }
653
880
  function buildUmbrellaBody(extras) {
654
- const triggerBySkill = new Map(
655
- extras.availableCommands.map((c) => [c.meta.invokes_skill, c.meta.trigger])
656
- );
881
+ const triggersBySkill = /* @__PURE__ */ new Map();
882
+ for (const c of extras.availableCommands) {
883
+ const triggers = triggersBySkill.get(c.meta.invokes_skill) ?? [];
884
+ triggers.push(c.meta.trigger);
885
+ triggersBySkill.set(c.meta.invokes_skill, triggers);
886
+ }
657
887
  const skillLines = extras.availableSkills.map((s) => {
658
- const trigger = triggerBySkill.get(s.meta.id);
659
- const label = trigger ? `\`${s.meta.id}\` (\`${trigger}\`)` : `\`${s.meta.id}\``;
888
+ const triggers = triggersBySkill.get(s.meta.id) ?? [];
889
+ const label = triggers.length > 0 ? `\`${s.meta.id}\` (${triggers.map((t) => `\`${t}\``).join(", ")})` : `\`${s.meta.id}\``;
660
890
  return `- ${label} \u2014 ${s.meta.description.split("\n")[0]}`;
661
891
  });
662
892
  const sections = [
@@ -676,11 +906,17 @@ function buildUmbrellaBody(extras) {
676
906
  ...extras.hasQualityDoc ? [
677
907
  "- `docs/quality/code-quality.md` \u2014 the project's code-quality rules: mechanical checks, judgment rules, accepted deviations. Read it before writing or auditing code."
678
908
  ] : [],
909
+ ...extras.hasIntents ? [
910
+ "- `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."
911
+ ] : [],
679
912
  "",
680
913
  "## Doc-first",
681
914
  "",
682
915
  "The order is: **understand the docs \u2192 fill the gaps \u2192 code \u2192 update the docs \u2192 commit**. If the docs are silent or stale on something you change, fill the gap upfront with the doc-skill writers \u2014 not downstream, not after the fact.",
683
916
  "",
917
+ ...extras.hasIntents ? [
918
+ "- Visible change of behavior \u2192 a `proposed` intent first (`/intent <verb + object>`), never the code first."
919
+ ] : [],
684
920
  "- Missing spec for a subsystem you touch \u2192 **do not code**, report the gap.",
685
921
  "- Implicit structural decision in your changes \u2192 an ADR (`/decision`).",
686
922
  "- Changed feature behavior \u2192 update the matching handbook (`/handbook`).",
@@ -809,6 +1045,23 @@ function getRenderer(engine) {
809
1045
  return RENDERERS[engine];
810
1046
  }
811
1047
 
1048
+ // src/renderers/intents-index.ts
1049
+ 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 .`.";
1050
+ function buildIntentsIndex(intentFiles) {
1051
+ const lines = ["# Intents", "", INTRO, ""];
1052
+ const sorted = [...intentFiles].sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : 0);
1053
+ for (const intentFile of sorted) {
1054
+ const status = intentFile.meta?.status ?? "proposed";
1055
+ const actors = intentFile.meta?.actors.join(", ") ?? "";
1056
+ lines.push(`- [${intentFile.title}](./${intentFile.file}) \u2014 ${status} \xB7 ${actors}`);
1057
+ for (const node of intentFile.nodes) {
1058
+ lines.push(`${" ".repeat(node.level)}- ${node.title} \u2014 ${node.effectiveStatus ?? status}`);
1059
+ }
1060
+ }
1061
+ return `${lines.join("\n")}
1062
+ `;
1063
+ }
1064
+
812
1065
  // src/render.ts
813
1066
  var RenderError = class extends Error {
814
1067
  constructor(message) {
@@ -878,12 +1131,16 @@ function render(input) {
878
1131
  availableSkills: Array.from(exposedSkills.values()),
879
1132
  availableCommands: Array.from(exposedCmds.values()),
880
1133
  hasProjectSkills: (input.projectSkills?.length ?? 0) > 0,
881
- hasQualityDoc: input.hasQualityDoc === true
1134
+ hasQualityDoc: input.hasQualityDoc === true,
1135
+ hasIntents: (input.intentFiles?.length ?? 0) > 0
882
1136
  });
883
1137
  files.push({ path: "AGENTS.md", content: umbrellaContent });
884
1138
  if (engines.includes("claude-code")) {
885
1139
  files.push({ path: "CLAUDE.md", content: CLAUDE_MD_STUB });
886
1140
  }
1141
+ if (input.intentFiles && input.intentFiles.length > 0) {
1142
+ files.push({ path: INTENTS_INDEX_PATH, content: buildIntentsIndex(input.intentFiles) });
1143
+ }
887
1144
  return { files, warnings };
888
1145
  }
889
1146
 
@@ -915,7 +1172,8 @@ function planInit(args) {
915
1172
  const overrides = args.overridesDir ? loadOverrides(args.overridesDir) : void 0;
916
1173
  const projectSkills = loadProjectSkills(args.targetDir);
917
1174
  const hasQualityDoc = existsSync6(join7(args.targetDir, QUALITY_DOC_PATH));
918
- const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc });
1175
+ const intentFiles = loadIntentFiles(args.targetDir);
1176
+ const output = render({ harness, engines, overrides, projectSkills, hasQualityDoc, intentFiles });
919
1177
  return { engines, output };
920
1178
  }
921
1179
 
@@ -962,7 +1220,7 @@ var generatedFresh = {
962
1220
  const full = join8(repoRoot, file.path);
963
1221
  if (!existsSync7(full)) {
964
1222
  issues.push(issue(file.path, `generated file is missing; ${FIX}`));
965
- } else if (readFileSync5(full, "utf8") !== file.content) {
1223
+ } else if (readFileSync6(full, "utf8") !== file.content) {
966
1224
  issues.push(
967
1225
  issue(
968
1226
  file.path,
@@ -993,7 +1251,8 @@ var FORBIDDEN_GITIGNORE_ENTRIES = [
993
1251
  ".codex/",
994
1252
  ".agents/",
995
1253
  ".opencode/",
996
- ".harness-manifest.json"
1254
+ ".harness-manifest.json",
1255
+ "docs/intents/README.md"
997
1256
  ];
998
1257
  function gitignoreEntries(text) {
999
1258
  const entries = /* @__PURE__ */ new Set();
@@ -1052,9 +1311,211 @@ var gitignoreHarness = {
1052
1311
  }
1053
1312
  };
1054
1313
 
1314
+ // src/linters/intent-anchors.ts
1315
+ var intentAnchors = {
1316
+ id: "lint:intent-anchors",
1317
+ pillars: ["intents"],
1318
+ defaultSeverity: "error",
1319
+ suggestedSkills: ["/intent"],
1320
+ run(repoRoot) {
1321
+ const issues = [];
1322
+ for (const intentFile of readIntentFiles(repoRoot)) {
1323
+ for (const node of intentFile.nodes) {
1324
+ if (node.effectiveStatus === "deprecated") continue;
1325
+ for (const anchor of node.anchors) {
1326
+ if (trackedPathExists(repoRoot, anchor)) continue;
1327
+ issues.push({
1328
+ linter: this.id,
1329
+ severity: "error",
1330
+ file: intentFile.path,
1331
+ line: node.line,
1332
+ message: `"${node.title}": anchor matches no file: ${anchor}`
1333
+ });
1334
+ }
1335
+ }
1336
+ }
1337
+ return issues;
1338
+ }
1339
+ };
1340
+
1341
+ // src/linters/intent-graph.ts
1342
+ var intentGraph = {
1343
+ id: "lint:intent-graph",
1344
+ pillars: ["intents"],
1345
+ defaultSeverity: "warning",
1346
+ suggestedSkills: ["/intent"],
1347
+ run(repoRoot) {
1348
+ const intentFiles = readIntentFiles(repoRoot);
1349
+ const terminals = intentFiles.flatMap(
1350
+ (intentFile) => intentFile.nodes.filter((node) => node.isTerminal).map((node) => ({ intentFile, node }))
1351
+ );
1352
+ const created = new Set(terminals.flatMap(({ node }) => node.creates));
1353
+ const issues = [];
1354
+ for (const { intentFile, node } of terminals) {
1355
+ for (const entity of node.requires) {
1356
+ if (created.has(entity)) continue;
1357
+ issues.push({
1358
+ linter: this.id,
1359
+ severity: "warning",
1360
+ file: intentFile.path,
1361
+ line: node.line,
1362
+ message: `"${node.title}": entity \`${entity}\` is required here but no terminal intent creates it`
1363
+ });
1364
+ }
1365
+ }
1366
+ return issues;
1367
+ }
1368
+ };
1369
+
1370
+ // src/linters/intent-util.ts
1371
+ import { posix } from "path";
1372
+ function intentFileSpecs(meta) {
1373
+ if (!meta) return [];
1374
+ return typeof meta.spec === "string" ? [meta.spec] : [...meta.spec];
1375
+ }
1376
+ function resolveSpecPath(filePath, spec) {
1377
+ const withoutFragment = spec.split("#")[0] ?? "";
1378
+ return posix.normalize(posix.join(posix.dirname(filePath), withoutFragment));
1379
+ }
1380
+
1381
+ // src/linters/intent-schema.ts
1382
+ var DERIVABLE_FIELDS = /* @__PURE__ */ new Set(["uses", "guards"]);
1383
+ var intentSchema = {
1384
+ id: "lint:intent-schema",
1385
+ pillars: ["intents"],
1386
+ defaultSeverity: "error",
1387
+ suggestedSkills: ["/intent"],
1388
+ run(repoRoot) {
1389
+ const issues = [];
1390
+ for (const intentFile of readIntentFiles(repoRoot)) {
1391
+ const report = (message, line) => {
1392
+ issues.push({
1393
+ linter: this.id,
1394
+ severity: "error",
1395
+ file: intentFile.path,
1396
+ ...line !== void 0 ? { line } : {},
1397
+ message
1398
+ });
1399
+ };
1400
+ for (const error of intentFile.errors) report(error.message, error.line);
1401
+ for (const spec of intentFileSpecs(intentFile.meta)) {
1402
+ if (!fileExists(repoRoot, resolveSpecPath(intentFile.path, spec))) {
1403
+ report(`frontmatter \`spec\` does not resolve: ${spec}`, 1);
1404
+ }
1405
+ }
1406
+ for (const node of intentFile.nodes) {
1407
+ const at = (message) => report(`"${node.title}": ${message}`, node.line);
1408
+ for (const { key, line } of node.unknownFields) {
1409
+ report(
1410
+ DERIVABLE_FIELDS.has(key) ? `"${node.title}": \`${key}:\` is derivable, never declared` : `"${node.title}": unknown field \`${key}:\``,
1411
+ line
1412
+ );
1413
+ }
1414
+ if (node.spec !== void 0 && !fileExists(repoRoot, resolveSpecPath(intentFile.path, node.spec))) {
1415
+ report(`"${node.title}": \`spec:\` does not resolve: ${node.spec}`, node.fieldLines.spec);
1416
+ }
1417
+ if (!node.isTerminal) {
1418
+ for (const field of TERMINAL_FIELDS) {
1419
+ const line = node.fieldLines[field];
1420
+ if (line !== void 0) {
1421
+ report(
1422
+ `"${node.title}": \`${field}:\` is a field of a terminal intent, this node has sub-intents`,
1423
+ line
1424
+ );
1425
+ }
1426
+ }
1427
+ continue;
1428
+ }
1429
+ if (Object.keys(node.fieldLines).length === 0) {
1430
+ at("a terminal intent carries at least one field");
1431
+ continue;
1432
+ }
1433
+ if (node.effectiveStatus === "implemented" && node.anchors.length === 0) {
1434
+ at("an `implemented` intent needs `anchors:`");
1435
+ }
1436
+ if (node.effectiveStatus === "proposed" && node.acceptance.length === 0) {
1437
+ at("a `proposed` intent needs `acceptance:` with at least one `- ` item");
1438
+ }
1439
+ }
1440
+ }
1441
+ return issues;
1442
+ }
1443
+ };
1444
+
1445
+ // src/linters/intent-vocabulary.ts
1446
+ var VOCABULARY_HEADING = /^#+\s*(\d+(\.\d+)*\.?\s*)?(Vocabulary|Vocabulaire)\b/i;
1447
+ var TERM = /^\s*[-*]\s+\*\*([^*]+)\*\*/;
1448
+ function entitySlug(term) {
1449
+ return term.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
1450
+ }
1451
+ function vocabularyOf(specText) {
1452
+ const lines = maskFencedCode(specText.split(/\r?\n/));
1453
+ let depth;
1454
+ let terms;
1455
+ for (const line of lines) {
1456
+ const heading = parseHeading(line);
1457
+ if (depth !== void 0) {
1458
+ if (heading && heading.depth <= depth) break;
1459
+ const term = TERM.exec(line)?.[1];
1460
+ if (term) terms?.add(entitySlug(term));
1461
+ continue;
1462
+ }
1463
+ if (heading && VOCABULARY_HEADING.test(line)) {
1464
+ depth = heading.depth;
1465
+ terms = /* @__PURE__ */ new Set();
1466
+ }
1467
+ }
1468
+ return terms;
1469
+ }
1470
+ var intentVocabulary = {
1471
+ id: "lint:intent-vocabulary",
1472
+ pillars: ["intents"],
1473
+ defaultSeverity: "error",
1474
+ suggestedSkills: ["/spec"],
1475
+ run(repoRoot) {
1476
+ const issues = [];
1477
+ for (const intentFile of readIntentFiles(repoRoot)) {
1478
+ const used = intentFile.nodes.flatMap(
1479
+ (node) => [...node.requires, ...node.creates].map((entity) => ({ entity, node }))
1480
+ );
1481
+ if (used.length === 0) continue;
1482
+ const specs = intentFileSpecs(intentFile.meta).map((spec) => resolveSpecPath(intentFile.path, spec)).filter((path) => fileExists(repoRoot, path));
1483
+ if (specs.length === 0) continue;
1484
+ const entities = /* @__PURE__ */ new Set();
1485
+ let hasVocabulary = false;
1486
+ for (const spec of specs) {
1487
+ const terms = vocabularyOf(readText(repoRoot, spec));
1488
+ if (!terms) continue;
1489
+ hasVocabulary = true;
1490
+ for (const term of terms) entities.add(term);
1491
+ }
1492
+ if (!hasVocabulary) {
1493
+ issues.push({
1494
+ linter: this.id,
1495
+ severity: "warning",
1496
+ file: intentFile.path,
1497
+ message: `no Vocabulary section in ${specs.join(", ")}; entities not checked`
1498
+ });
1499
+ continue;
1500
+ }
1501
+ for (const { entity, node } of used) {
1502
+ if (entities.has(entity)) continue;
1503
+ issues.push({
1504
+ linter: this.id,
1505
+ severity: "error",
1506
+ file: intentFile.path,
1507
+ line: node.line,
1508
+ message: `"${node.title}": entity \`${entity}\` is not a Vocabulary term of ${specs.join(", ")}`
1509
+ });
1510
+ }
1511
+ }
1512
+ return issues;
1513
+ }
1514
+ };
1515
+
1055
1516
  // src/linters/orphan-decisions.ts
1056
- import { basename as basename2 } from "path";
1057
- import fg5 from "fast-glob";
1517
+ import { basename as basename3 } from "path";
1518
+ import fg4 from "fast-glob";
1058
1519
  var orphanDecisions = {
1059
1520
  id: "lint:orphan-decisions",
1060
1521
  pillars: ["decisions"],
@@ -1065,7 +1526,7 @@ var orphanDecisions = {
1065
1526
  const issues = [];
1066
1527
  const adrs = listMarkdown(repoRoot, "docs/decisions");
1067
1528
  if (adrs.length === 0) return issues;
1068
- const otherDocs = fg5.sync("**/*.md", {
1529
+ const otherDocs = fg4.sync("**/*.md", {
1069
1530
  cwd: repoRoot,
1070
1531
  absolute: false,
1071
1532
  ignore: [
@@ -1082,7 +1543,7 @@ var orphanDecisions = {
1082
1543
  });
1083
1544
  const referenceCorpus = otherDocs.map((f) => readText(repoRoot, f)).join("\n");
1084
1545
  for (const adr of adrs) {
1085
- const filename = basename2(adr);
1546
+ const filename = basename3(adr);
1086
1547
  const stem = filename.replace(/\.md$/, "");
1087
1548
  const referenced = referenceCorpus.includes(filename) || referenceCorpus.includes(stem);
1088
1549
  if (!referenced) {
@@ -1258,33 +1719,42 @@ var specTechAgnostic = {
1258
1719
  };
1259
1720
 
1260
1721
  // src/linters/tracks-drift.ts
1261
- import fg6 from "fast-glob";
1722
+ import fg5 from "fast-glob";
1262
1723
  var TRACKED_DIRS2 = ["docs/handbook", "docs/tests", "docs/workflow"];
1724
+ var INTENTS_DIR2 = "docs/intents";
1263
1725
  var DEFAULT_DRIFT_THRESHOLD = 10;
1264
1726
  function expandGlob(repoRoot, pattern) {
1265
1727
  if (pattern.includes("*")) {
1266
- return fg6.sync(pattern, { cwd: repoRoot, absolute: false });
1728
+ return fg5.sync(pattern, { cwd: repoRoot, absolute: false });
1267
1729
  }
1268
1730
  return [pattern];
1269
1731
  }
1732
+ function trackedPaths(dir, file, text, data) {
1733
+ if (dir === INTENTS_DIR2) {
1734
+ const anchors = parseIntentFile(file, text).nodes.flatMap((node) => node.anchors);
1735
+ return anchors.length > 0 ? [...new Set(anchors)] : void 0;
1736
+ }
1737
+ return Array.isArray(data.tracks) ? data.tracks : void 0;
1738
+ }
1270
1739
  var tracksDrift = {
1271
1740
  id: "lint:tracks-drift",
1272
- pillars: ["handbook", "tests", "workflow"],
1741
+ pillars: ["handbook", "tests", "workflow", "intents"],
1273
1742
  defaultSeverity: "warning",
1274
1743
  suggestedSkills: ["/drift", "/handbook"],
1275
1744
  run(repoRoot) {
1276
1745
  const issues = [];
1277
- for (const dir of TRACKED_DIRS2) {
1746
+ for (const dir of [...TRACKED_DIRS2, INTENTS_DIR2]) {
1278
1747
  const files = listMarkdown(repoRoot, dir);
1279
1748
  for (const f of files) {
1280
1749
  const text = readText(repoRoot, f);
1281
1750
  const { data } = parseFrontmatter(text);
1282
- if (!Array.isArray(data.tracks)) continue;
1751
+ const tracks = trackedPaths(dir, f, text, data);
1752
+ if (!tracks) continue;
1283
1753
  const docCommit = gitLastCommitForPath(repoRoot, f);
1284
1754
  if (!docCommit) continue;
1285
1755
  const threshold = typeof data.driftThreshold === "number" && data.driftThreshold > 0 ? data.driftThreshold : DEFAULT_DRIFT_THRESHOLD;
1286
1756
  let driftCount = 0;
1287
- for (const tracked of data.tracks) {
1757
+ for (const tracked of tracks) {
1288
1758
  if (typeof tracked !== "string") continue;
1289
1759
  const targets = expandGlob(repoRoot, tracked);
1290
1760
  for (const t of targets.length > 0 ? targets : [tracked]) {
@@ -1321,6 +1791,10 @@ var ALL_LINTERS = [
1321
1791
  orphanDecisions,
1322
1792
  gitignoreHarness,
1323
1793
  qualitySchema,
1794
+ intentSchema,
1795
+ intentAnchors,
1796
+ intentVocabulary,
1797
+ intentGraph,
1324
1798
  generatedFresh
1325
1799
  ];
1326
1800
  function runLinters(repoRoot, opts = {}) {